# Stamp

> A definite “done” on any record, in ink: set it and the stamp lands with a press, the ink starts wet and dries into the grain, heavier where the pressure fell.

When an invoice is paid or an expense is approved, most apps change a small badge in a corner, and nobody can tell at a glance which records are finished. Stamp puts the mark on the record itself, the way it was done on paper. Wrap anything (an invoice, a row, a card) and set on: the stamp comes down, the record gives a fraction at the moment of contact, and the ink is left behind a touch larger than it will dry. Fresh, it’s full and glossy with a sheen across it; over about a second and a half it soaks in and goes matte, the grain of the surface showing through as small voids, heavier on the side the pressure fell, so no two stamps look alike. Unset it and the ink breaks up into the grain and is gone. It comes as a framed word with a line under it, or a round seal with the detail running round its rim, in a status colour or any colour you pass, and it reads under light and dark themes.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/stamp.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/stamp
- Registry item (source): https://hairlineui.com/r/stamp.json

## Usage

```tsx
import { Stamp } from "@/components/stamp";

<Stamp on={invoice.paid} mark="Paid" detail="15 Nov 2026">
  <InvoiceCard invoice={invoice} />
</Stamp>
```

## Marking an invoice paid

The stamp follows your data: set on when your server says it’s paid, and pass the date and method as the detail.

```tsx
"use client";
import { Stamp } from "@/components/stamp";

export function Invoice({ invoice }: { invoice: { id: string; paidAt?: string; method?: string } }) {
  const paid = Boolean(invoice.paidAt);
  const date = paid ? new Date(invoice.paidAt!).toLocaleDateString("en-GB", { day: "numeric", month: "short", year: "numeric" }) : "";
  return (
    <Stamp on={paid} mark="Paid" detail={paid ? `${date} · ${invoice.method}` : undefined} seed={invoice.id}>
      <InvoiceCard invoice={invoice} />
    </Stamp>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `on` | `boolean` | – | Stamped or not. Turning it on presses; off lifts. |
| `mark` | `string` | – | The word, set in capitals: Paid, Approved, Void, Shipped. |
| `detail` | `string` | – | A small line: a date, a reference, who. |
| `shape` | `"rect" \| "seal"` | `"rect"` | A framed word, or a round seal with the detail round its rim. |
| `tone` | `"success" \| "danger" \| "warning" \| "primary" \| "neutral"` | `"success"` | Ink colour by meaning, with a lighter pair in dark mode. |
| `color` | `string` | – | Any CSS colour, instead of tone. |
| `position` | `"center" \| "top-right" \| "bottom-right"` | `"center"` | Where it lands on what it wraps. |
| `rotate` | `number` | `-9` | Degrees; a hand stamp is never quite straight. |
| `size` | `number` | `1` | 1 is a 30px word. |
| `seed` | `string` | `the word and detail` | Changes the grain; pass a record id so each stamp dries its own way. |
| `sound` | `boolean` | `false` | A soft knock as it lands. |

## States

- **press**: The ink appears at 107% within 40ms and settles to full size over 170ms with a slight overshoot; the wrapped record scales to 98.8% and back over 180ms.
- **wet**: Fresh ink is near full strength with a diagonal sheen of light across it.
- **dry**: Over 1.5s the wet print crossfades into the dry one: matte, with voids where the grain is open and the pressure light, the edges a little rough.
- **lift**: Unset, the dry ink breaks up into the grain over 520ms, the thinnest parts first, and is gone.
- **already on**: If on is true the first time it renders, the stamp is simply there, dry.
- **reduced motion**: No press, drying or lift: the stamp appears dry and disappears in place.

## What it handles

A small status badge in the corner of a record doesn’t say “this one is done” at a glance, and changing it gives no moment for the person who did it.

- **On anything**: Wraps any element and lands over it; nothing about the record has to change.
- **Reads as ink**: Wet with a sheen when it lands, matte with grain once dry, heavier on one side.
- **Never the same twice**: The grain comes from a seed (the word by default), so each record’s stamp is its own.
- **Two faces**: A framed word with a line under it, or a round seal with the detail round its rim.
- **Already stamped**: A record that’s already done shows its stamp dry, with no press, the first time it appears.
- **Screen readers**: The record gains “Stamped: Paid, 15 Nov 2026”, and changes are announced once.

## Replaces

paid badge, status pill, approved label, watermark, done overlay

## Where it fits

- **Invoices**: Paid, overdue or void, on the invoice itself rather than in a badge.
- **Approvals**: An expense, a time sheet or a purchase order a manager has signed off.
- **Orders and tickets**: Shipped, refunded, used: the state of a record anyone can read from across a list.
- **Contracts and checks**: Signed, verified, received, with who and when on the stamp.

## Notes

- The stamp is drawn once per word, colour, size and seed onto a small canvas over the record: a wet print, a dry print and a noise field for the lift. Drying is a crossfade between the two prints; the lift writes pixels for about half a second. Nothing runs when it’s still.
- The ink multiplies with what’s under it in light themes, so text beneath stays readable through it, and sits on top in dark themes. Status tones use emerald, red and amber with dark pairs; primary and neutral follow your theme.
- The stamp is decoration over the record and hidden from screen readers; the record gains a short “Stamped: …” line, and turning it on or off is announced once.
- Reduced motion drops the press, the drying and the lift.

License: MIT (https://hairlineui.com/license#components)
