Paper

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add paper

Usage#

import {
  Paper,
  PaperField,
  PaperHeader,
  PaperHeading,
  PaperRow,
  PaperSection,
  PaperTitle,
} from "@/components/ui/paper"

export function Example() {
  return (
    <Paper>
      <PaperHeader>
        <PaperHeading>
          <PaperTitle>Delivery Note</PaperTitle>
        </PaperHeading>
      </PaperHeader>
      <PaperSection>Consignee</PaperSection>
      <PaperRow>
        <PaperField label="Name" grow={2}>Priya Raman</PaperField>
        <PaperField label="Packages">3</PaperField>
      </PaperRow>
    </Paper>
  )
}

Anatomy#

Every part is optional but the sheet. A ticket can be a heading and three rows; a contract uses the lot. Parts stack in the order you write them, each ruled off the next.

import {
  Paper,
  PaperBox,
  PaperCaption,
  PaperCheckItem,
  PaperChecklist,
  PaperField,
  PaperFooter,
  PaperHeader,
  PaperHeaderAside,
  PaperHeading,
  PaperNote,
  PaperRow,
  PaperSeal,
  PaperSection,
  PaperSignature,
  PaperSignatures,
  PaperSubtitle,
  PaperTable,
  PaperTableCell,
  PaperTableHead,
  PaperText,
  PaperTitle,
} from "@/components/ui/paper"

<Paper>
  {/* The letterhead: a seal, the centered heading, an aside of boxes */}
  <PaperHeader>
    <PaperSeal>{/* an img or an svg */}</PaperSeal>
    <PaperHeading>
      <PaperTitle />
      <PaperSubtitle />
      <PaperCaption />
    </PaperHeading>
    <PaperHeaderAside>
      <PaperBox label="Number" />
    </PaperHeaderAside>
  </PaperHeader>

  {/* The body: bands, rows of fields, copy, tables, checklists */}
  <PaperSection />
  <PaperRow>
    <PaperField label="Label" grow={2} />
  </PaperRow>
  <PaperText />
  <PaperTable>
    <PaperTableHead />
    <PaperTableCell />
  </PaperTable>
  <PaperNote />
  <PaperChecklist>
    <PaperCheckItem checked />
  </PaperChecklist>

  {/* Signature lines, side by side, and the small print */}
  <PaperSignatures>
    <PaperSignature label="Signature" name="Name" date="Date" />
  </PaperSignatures>
  <PaperFooter />
</Paper>

Fit#

A document is not responsive. The sheet is laid out at one design width, width in em (52 by default, 832px at a 16px root), and with fit it scales as a whole to the width it is given: the title stays on one line, a label never breaks in two and the copy keeps its line breaks, at any size. The scale is the sheet's own font size, and every length inside is in em, so the page is laid out again for real rather than zoomed. It never grows past its design size: in a wider column it sits centered.

fit={false} keeps the design width whatever the room, and the frame decides what happens to the overflow: here it scrolls sideways. frameClassName styles that frame, the div the sheet measures; padding on it is room the sheet keeps clear, for its shadow.

Letterhead#

PaperHeader lays out a PaperSeal, the PaperHeading and a PaperHeaderAside, in that order. The seal and the aside are boxes of the same width, so the heading between them is centered on the sheet, not on the room they leave. The title wraps rather than run under the boxes; captions stack under the subtitle. The seal takes any img or svg: the Seal on these pages is a small inline SVG of the docs' own, drawn in var(--paper-accent) so it follows the sheet's accent.

Drop the seal or the aside and keep the other side's box empty (<PaperSeal /> or <PaperHeaderAside />) to hold the heading on the sheet's axis, or drop both and give the heading the whole row.

Fields and boxes#

A PaperRow is a ruled line of PaperFields: a pre-printed label over a typed-in value. grow is a field's share of the row, a flex factor. When a label wraps onto two lines the values in the row still sit on one line, and a value too long for its cell ends in an ellipsis. PaperBox is the same pair boxed on its own, for the aside: a number, a status, a date.

Running text#

PaperText is copy someone reads: terms, a statement, a narrative. It is justified in the serif and keeps the line breaks it was typed with, so text straight from a textarea or a database lands as it was written, paragraphs and numbered clauses included.

Tables#

PaperTable is a plain table: write the thead and tbody yourself with PaperTableHead, printed like a field label, and PaperTableCell, typed in. Widths are yours too; percentages hold at every scale. When a section has nothing to list, PaperNote says so in place of an empty table.

Checklist#

PaperChecklist is a list of printed boxes and PaperCheckItem one line of it, ticked with checked. It records what was done; nothing on the sheet can be toggled, so the box is drawn, not a control.

Signatures#

PaperSignatures sets PaperSignature blocks side by side: a label, the mark over a line, and the name and date under it. The mark is the children: a stored signature as an img (here the SVG a SignaturePad submits), a Signature, or a live SignaturePad given absolute inset-0 so it takes the whole box. Sign the right-hand line: the pad maps the pointer with getBoundingClientRect(), which the sheet's scale never skews, and the date fills in when the first stroke lands. The app's own controls, like Clear here, sit outside the sheet. Left empty, a line waits to be signed.

PreviewCode

Equipment Handover

Northwind Freight Co.

Acknowledgement

I received the handheld scanner HS-40 (serial 7Q2-118-604), its charging dock and a safety vest in working order, and I will return them on my last day of work.

Issued by

Maya Chen, HR Director10/04/2026

Received by

Sign here

Daniel Ortega Ruiz

Clear signature

Re-tinting#

The sheet's inks are its own roles, derived from the light theme's tokens: --paper-ink, --paper-muted, --paper-rule, --paper-label (the label tint) and --paper-accent (the title, the section bands and anything you paint with it, like the seal here). The accent defaults to a letterhead navy; set any of them per sheet with a utility.

Old engines#

Paper is built to hold in old embedded Chromium too, the kind a desktop or game shell ships (Chromium 10x): no container queries, no :has() and no standalone translate or scale anywhere. The fit is one ResizeObserver and one font size; without the observer the sheet is measured once, on mount. Because nothing is zoomed or transformed, a control set into the paper reads its pointer and its box as it would anywhere else, and the type is rasterized at the size it is shown, crisp.

API reference#

FAQ#