> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cardholder Name Input

> Input for cardholder name on payment forms.

## \<primer-input-card-holder-name>

Input for collecting the cardholder's name. Updates card form context in real-time as user types.

## Quick Reference

| | |
| - | - |
| **Parent** | `<primer-card-form>` |
| **Properties** | `label`, `placeholder`, `aria-label` |
| **Configuration** | Via SDK options |

***

## Examples

### Default

```html theme={"dark"}
<primer-card-form>
  <primer-input-card-holder-name></primer-input-card-holder-name>
</primer-card-form>
```

### Custom Labels

```html theme={"dark"}
<primer-input-card-holder-name
  label="Name on Card"
  placeholder="Enter your full name"
  aria-label="Full name as it appears on your card"
></primer-input-card-holder-name>
```

### In Custom Layout

```html theme={"dark"}
<primer-card-form>
  <div slot="card-form-content">
    <primer-input-card-holder-name></primer-input-card-holder-name>
    <primer-input-card-number></primer-input-card-number>
    <div style="display: flex; gap: 8px;">
      <primer-input-card-expiry></primer-input-card-expiry>
      <primer-input-cvv></primer-input-cvv>
    </div>
    <button type="submit">Pay</button>
  </div>
</primer-card-form>
```

***

## Properties

| Property | Attribute | Type | Default | Description |
| - | - | - | - | - |
| `label` | `label` | `string` | `"Cardholder Name"` | Label text |
| `placeholder` | `placeholder` | `string` | `"Name on card"` | Placeholder text |
| `ariaLabel` | `aria-label` | `string` | Value of `label` | Screen reader label |

***

## Configuration

Control visibility and requirement via SDK options:

```javascript theme={"dark"}
checkout.options = {
  card: {
    cardholderName: {
      visible: true,      // Show field (default: true)
      required: true,     // Make required (default: true)
      defaultValue: ''    // Pre-fill value
    }
  }
};
```

***

## Pre-filling

### Via SDK options (recommended)

```javascript theme={"dark"}
checkout.options = {
  card: {
    cardholderName: {
      defaultValue: 'John Doe'
    }
  }
};
```

### Via primer:ready event

```javascript theme={"dark"}
checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail;
  primer.setCardholderName('John Doe');
});
```

***

## Events

`<primer-input-card-holder-name>` does not emit its own events. Validation and submission are managed by the parent `<primer-card-form>`.

### Relevant Parent Events

| Event | Emitted by | How it affects this input |
| - | - | - |
| `primer:card-submit` | `<primer-card-form-submit>` or external dispatch | Triggers validation — if this field is required and empty, an error message displays below it |
| `primer:card-error` | `<primer-card-form>` | Emitted when any card input fails validation — payload includes all validation errors |
| `primer:card-success` | `<primer-card-form>` | Emitted when the form submits successfully |
| `primer:ready` | `<primer-checkout>` | Provides the `PrimerJS` instance, which exposes `setCardholderName()` for pre-filling |

***

## CSS Properties

This component uses the shared [Input Styling Tokens](https://primer.io/docs/sdk/primer-checkout-web/styling-variables.md#input-styling-tokens).

### Typography

| Property | Description | Default |
| - | - | - |
| `--primer-typography-body-large-size` | Input text size | `16px` |
| `--primer-typography-body-large-weight` | Input text weight | `400` |
| `--primer-typography-body-small-size` | Label text size | `12px` |

### Colors

| Property | Description |
| - | - |
| `--primer-color-text-primary` | Input text color |
| `--primer-color-text-placeholder` | Placeholder text color |
| `--primer-color-text-disabled` | Disabled text color |
| `--primer-color-text-negative` | Error message color |

### Border & Background

| Property | Description |
| - | - |
| `--primer-radius-small` | Input border radius |
| `--primer-color-border-outlined-default` | Default border |
| `--primer-color-border-outlined-focus` | Focus border |
| `--primer-color-border-outlined-error` | Error border |
| `--primer-color-background-outlined-default` | Default background |

### Spacing

| Property | Description | Default |
| - | - | - |
| `--primer-space-xsmall` | Gap between label and input | `4px` |
| `--primer-space-medium` | Input padding | `12px` |

### Animation

| Property | Description | Default |
| - | - | - |
| `--primer-animation-duration` | Transition duration | `200ms` |
| `--primer-animation-easing` | Transition easing | `cubic-bezier(0.44, 0, 0.4, 1)` |

***

## States

| State | Description | Visual Change |
| - | - | - |
| **Default** | Initial state | Standard border and background |
| **Hover** | Mouse over input | Border darkens slightly |
| **Focus** | Input is focused | Blue border, increased width |
| **Filled** | Name entered | Standard appearance |
| **Error** | Required but empty on submit | Red border, error message below |
| **Disabled** | Form or input disabled | Muted colors, no interaction |
| **Hidden** | `visible: false` in options | Not rendered |

***

## Usage Guidelines

### Do

* Place inside `<primer-card-form>`
* Configure via SDK options
* Use `defaultValue` to pre-fill from user profile

### Don't

* Don't place outside card form context

***

## Content Guidelines

### Label

| Do | Don't |
| - | - |
| "Name on card" | "Cardholder name" (too formal) |
| "Full name" (when context is clear) | "First and last name" (not all naming conventions use this split) |

### Placeholder

| Do | Don't |
| - | - |
| Empty placeholder (cleanest) | "John Doe" (culturally specific) |
| "As shown on card" (helpful hint) | "Enter your name" (redundant with label) |

### Error messages

| Do | Don't |
| - | - |
| "Enter the name on your card" | "Required" |
| "Name is required" | "Invalid name" (ambiguous) |

***

## See also

> [card] [primer-card-form](https://primer.io/docs/sdk/primer-checkout-web/components/primer-card-form/primer-card-form.md)
>
> Parent container

> [card] [SDK options](https://primer.io/docs/sdk/primer-checkout-web/sdk-options-reference.md)
>
> Configuration options


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.