Card field

A React component in Beamline's Form controls category.

A payment card in one field: the number groups as it is typed and names its network, the expiry and security code follow on their own as each part completes, the number is checked (length and checksum) and the expiry must be in the future; when it is complete and you move on, the number folds to its last four digits.

Use it for

Taking a card in a checkout, a billing settings page or an add-payment-method dialog, when your payment provider accepts raw card details from your own page (or for a design and prototype of that page).

Not for

When the provider requires its own hosted iframe for card data (render the provider's element, styled like the system's fields).
Bank account or IBAN numbers (input with its own pattern).
Showing a saved card (item or card with the last four digits).

Anatomy

label above (the field's), one frame: the network's mark (a word: Visa, Mastercard, Amex… or a plain card), the number, MM / YY, CVC and an optional postal code
a narrow field (under 22rem) puts the number on its own row and the rest under it, inside the same frame
the message line under the field: help, or the first problem in words (incomplete, does not check out, expired, wrong length)
complete and left: the number shows as •••• 4242 until focus comes back

Variants

size: sm, md, lg

States

empty
typing
network recognised
complete
invalid number
expired
incomplete
disabled
error from your payment provider (error prop)

Keyboard

Tab moves through number, expiry, CVC and postal code
A part that is complete and valid moves focus to the next by itself; Backspace in an empty part goes back to the end of the one before
Pasting a whole card number (with spaces or dashes) fills it; pasting “12/28” or “1228” fills the expiry
Only digits are taken; the browser's saved cards fill every part through autocomplete

Motion

The network's word cross-fades in when the number is recognised and out when it is not. A part that completes passes focus at once (nothing waits). When the field is complete and left, the number folds to •••• 4242 (the hidden digits fade, the last four slide into place) and unfolds when focused again. A problem line grows in under the field (the shared field message). Reduced motion keeps the fades.

Props

Prop	Type	Default	Description
`label` (required)	`ReactNode`	—
`hideLabel`	`boolean`	—
`value / defaultValue / onValueChange`	`CardValue / (value: CardValue) => void`	—
`postalCode`	`boolean`	—	Ask for a postal code too. Default false.
`brands`	`CardBrand[]`	—	Networks you accept; another one is refused in words (“We don't take Amex”).
`description / error`	`ReactNode`	—	error is your payment provider's answer (declined, expired) shown on the line under the field.
`size`	`"sm" \| "md" \| "lg"`	—
`disabled / required / name / id`	`boolean / string`	—
`className / classNames / style / ref`	`root`	—

Dependencies

lucide-react

Import

import { CardField } from "@/components/card-field/card-field";

Get it

Card field is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent