# Pay button

> The button at the end of a checkout, through the whole wait: the card being charged, a line of light while it pays, and a receipt that slides out from under it.

Most Pay buttons go grey and spin, and then the page changes or a toast says something. People tap twice, or leave not knowing if they paid. This one stays the place where the answer appears. Press it and the label turns into the card being charged, "Paying with Visa •• 4242", while a line of light laps the button for as long as your onPay runs. When it resolves, the line closes into a whole ring and lets go, the button turns green with a check drawn in it, and a receipt slides out from under it: the reference with a Copy button, the card and the time. If it throws, the button shakes once and says "Try again", and the reason slides out of the same slot; pressing again tucks it back in. The amount rolls when the total changes, so a coupon or a quantity change reads at once.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/pay-button.json
```

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

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `number-roll`
- Docs and live preview: https://hairlineui.com/ui/pay-button
- Registry item (source): https://hairlineui.com/r/pay-button.json

## Usage

```tsx
import { PayButton } from "@/components/pay-button";

<PayButton
  amount={48}
  method={{ brand: "Visa", last4: "4242" }}
  onPay={() => pay(order)}
/>
```

## With Stripe

Confirm the PaymentIntent your server created; resolve with its id as the reference, and throw Stripe's message when it is declined. Stripe's own element still takes the card details.

```tsx
"use client";
import { useElements, useStripe } from "@stripe/react-stripe-js";
import { PayButton } from "@/components/pay-button";

export function PayStep({ total, card }: { total: number; card: { brand: string; last4: string } }) {
  const stripe = useStripe();
  const elements = useElements();
  return (
    <PayButton
      amount={total}
      method={card}
      disabled={!stripe || !elements}
      onPay={async () => {
        const { error, paymentIntent } = await stripe!.confirmPayment({ elements: elements!, redirect: "if_required" });
        if (error) throw new Error(error.message ?? "The payment didn't go through.");
        return { reference: paymentIntent?.id };
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `amount` | `number` | – | The total on the button. It rolls when it changes. |
| `method` | `{ brand: string; last4?: string }` | – | The card or wallet being charged, named while paying and on the receipt. |
| `onPay` | `() => unknown \| Promise<unknown>` | – | Your payment. Resolve when it went through (with { reference } to show it on the receipt); throw an Error to show its message. |
| `format / locales` | `Intl.NumberFormatOptions / string \| string[]` | `{ style: "currency", currency: "USD" }` | How the amount is written. |
| `labels` | `{ pay?, paying?, paid?, retry?, failed? }` | – | The words. pay replaces the whole "Pay $48.00"; failed is the reason when the Error has no message. |
| `disabled` | `boolean` | `false` | Dimmed and unpressable, e.g. until the card details are complete. |
| `sound` | `boolean` | `false` | Two soft rising notes when it is paid, two falling ones when it is declined (synthesised, no files). |
| `onStatusChange` | `(status: "idle" \| "paying" \| "paid" \| "error") => void` | – | Every change of state. |

## States

- **idle**: A 48px pill in the primary colour: "Pay $48.00". When the amount changes, its digits roll the way it moved.
- **paying**: The label lifts out and "Paying with Visa •• 4242" rises in with a small card. A bright line with a faint tail laps the button 4px outside it, once every 1.4s, while onPay runs (at least 0.7s).
- **paid**: The line closes into a whole emerald ring that grows a little and fades (1.1s); the button turns green and a check draws itself before "Paid $48.00". The receipt slides out from under the button (0.52s): the reference with Copy, then the card and the time. It stays paid.
- **copied**: The Copy icon turns into a green check for 1.6s.
- **declined**: The button shakes once (±5px, 0.38s) and says "Try again"; the Error's message slides out of the slot in red. Pressing again tucks it back into the button as the line starts again.
- **reduced motion**: No lap, ring, shake or slide: a still outline shows while paying, and the labels and the receipt change in place.

## What it handles

The seconds after Pay are the most anxious in a checkout. The usual button spins with no word on which card is being charged, then hands the answer to a different screen, so people tap again or refresh.

- **Says what it charges**: While paying, the label names the card or wallet in use, so nobody wonders which one it was.
- **A wait you can see**: A line of light laps the button for as long as your onPay runs, at least long enough to be seen.
- **The answer in place**: Paid turns the button green and slides a receipt out from under it, with the reference ready to copy.
- **Declines say why**: The Error's message slides out of the same slot in red, and the button becomes Try again.
- **Never pays twice**: It ignores presses while paying and stays paid until it is remounted, so a double tap can't charge again.
- **Keyboard and screen readers**: A real button; paying, paid with its reference, and the decline reason are announced from a status region.

## Replaces

payment button loading state, payment success screen, payment declined message, checkout submit button, order confirmation toast

## Where it fits

- **Checkout**: The last button of a store's checkout, under the order summary.
- **Upgrade and billing**: Pay for a plan change or an overdue invoice inside the app.
- **Tickets and bookings**: Pay for seats or a stay, with the booking reference on the receipt.
- **Top-ups and tips**: Add credit to a wallet or tip a creator in one press.

## Notes

- A real button. While paying and once paid it is aria-disabled, so it keeps focus and ignores presses.
- Paying (with the card), paid (with the reference) and the decline reason are announced from a status region outside the button.
- onPay is called once per press, and never while one is in flight. It stays paid until it is remounted (a new key).
- The line of light is two dashes on one SVG outline, moved by the Web Animations API only while paying; nothing re-renders while it laps.
- The receipt sits in the layout under the button, so it pushes what follows down instead of covering it. Fills the width it is given (at least 248px).

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