# CreditCardInput

> Slug: `credit-card` · Category: Form Controls

## When to use

- Capturing a credit/debit card number in checkout, payment update, or wallet flows.
- When a leading card-outline icon is needed to signal "card number" visually.

## When NOT to use

- Generic short-numeric input (zip, OTP, etc.) — use `TextField` with `inputMode="numeric"`.
- Card expiration / CVV — use a plain `TextField` with appropriate `pattern` and `maxLength`.

## Variants & decision tree

`CreditCardInput` is a thin wrapper over `TextField` that fixes `type="text"`, `inputMode="numeric"`, and renders the leading card icon. All `TextField` props (except those it owns) pass through.

## States

Empty, focused, filled, error (`errorMessage`), disabled, read-only, required.

## Props

Inherits from `TextFieldProps` minus `type`, `inputMode`, and `hasLeadingCCIcon` (which are set internally).

| Prop | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | — | Required. Input id. |
| `label` | `string` | — | Required. Floating label (e.g., "Card number"). |
| `name` | `string` | — | Required for form submission. |
| `value` / `defaultValue` | `string` | — | Controlled / uncontrolled value. |
| `onChange` | `ChangeEventHandler` | — | Standard React handler. |
| `errorMessage` | `string` | — | Inline validation error. |
| `supportingText` | `string` | — | Helper text. |
| `disabled` | `boolean` | `false` | Disables input. |
| `required` | `boolean` | `false` | Required field marker. |
| `inverse` | `boolean` | `false` | Dark-background styling. |
| `maxLength` | `number` | — | Max characters (typically 19 with spaces). |
| `pattern` | `string` | — | Validation pattern. |

## Usage examples

```tsx
// Basic
<CreditCardInput id="cc" name="cardNumber" label="Card number" />

// Controlled with formatting
const [card, setCard] = useState('');
<CreditCardInput
  id="cc"
  name="cardNumber"
  label="Card number"
  value={card}
  onChange={(e) => setCard(formatCardNumber(e.target.value))}
  maxLength={19}
  required
/>

// Validation error
<CreditCardInput id="cc" name="cardNumber" label="Card number" defaultValue="1234" errorMessage="Please enter a valid card number" />
```

## Composition

Pair with separate `TextField` controls for expiration and CVV inside a payment form. Combine with `Select` for billing country and `Checkbox` for "Save this card".

## Accessibility

`id`, `label`, and `name` are required. The numeric `inputMode` triggers the digit keypad on mobile. The leading icon is decorative — the label provides the accessible name. Use `errorMessage` for inline validation; it wires `aria-invalid` and `aria-describedby` automatically.

## Do / Don't

- DO format the value on input (group digits in 4s) for readability.
- DO use `autoComplete="cc-number"` for browser autofill.
- DON'T validate prematurely — only show `errorMessage` after blur or submit.
- DON'T log or persist raw card numbers in client state beyond the form.
