<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
Custom Labels
In Custom Layout
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:Pre-filling
Via SDK options (recommended)
Via primer:ready event
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.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
defaultValueto 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) |
Related
- primer-card-form — Parent container
- SDK Options — Configuration options