Skip to main content

<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>
Propertieslabel, placeholder, aria-label
ConfigurationVia SDK options

Examples

Default

<primer-card-form>
  <primer-input-card-holder-name></primer-input-card-holder-name>
</primer-card-form>

Custom Labels

<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

<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

PropertyAttributeTypeDefaultDescription
labellabelstring"Cardholder Name"Label text
placeholderplaceholderstring"Name on card"Placeholder text
ariaLabelaria-labelstringValue of labelScreen reader label

Configuration

Control visibility and requirement via SDK options:
checkout.options = {
  card: {
    cardholderName: {
      visible: true,      // Show field (default: true)
      required: true,     // Make required (default: true)
      defaultValue: ''    // Pre-fill value
    }
  }
};

Pre-filling

checkout.options = {
  card: {
    cardholderName: {
      defaultValue: 'John Doe'
    }
  }
};

Via primer:ready event

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

EventEmitted byHow it affects this input
primer:card-submit<primer-card-form-submit> or external dispatchTriggers 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

PropertyDescriptionDefault
--primer-typography-body-large-sizeInput text size16px
--primer-typography-body-large-weightInput text weight400
--primer-typography-body-small-sizeLabel text size12px

Colors

PropertyDescription
--primer-color-text-primaryInput text color
--primer-color-text-placeholderPlaceholder text color
--primer-color-text-disabledDisabled text color
--primer-color-text-negativeError message color

Border & Background

PropertyDescription
--primer-radius-smallInput border radius
--primer-color-border-outlined-defaultDefault border
--primer-color-border-outlined-focusFocus border
--primer-color-border-outlined-errorError border
--primer-color-background-outlined-defaultDefault background

Spacing

PropertyDescriptionDefault
--primer-space-xsmallGap between label and input4px
--primer-space-mediumInput padding12px

Animation

PropertyDescriptionDefault
--primer-animation-durationTransition duration200ms
--primer-animation-easingTransition easingcubic-bezier(0.44, 0, 0.4, 1)

States

StateDescriptionVisual Change
DefaultInitial stateStandard border and background
HoverMouse over inputBorder darkens slightly
FocusInput is focusedBlue border, increased width
FilledName enteredStandard appearance
ErrorRequired but empty on submitRed border, error message below
DisabledForm or input disabledMuted colors, no interaction
Hiddenvisible: false in optionsNot 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

DoDon’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

DoDon’t
Empty placeholder (cleanest)“John Doe” (culturally specific)
“As shown on card” (helpful hint)“Enter your name” (redundant with label)

Error messages

DoDon’t
”Enter the name on your card""Required"
"Name is required""Invalid name” (ambiguous)