CVV Input

<primer-input-cvv>

Secure, PCI-compliant input for card security codes (CVV/CVC). Uses iframe for maximum security.

Quick Reference


Parent	`<primer-card-form>`
Properties	`label`, `placeholder`, `aria-label`
Features	Secure iframe, validation

Examples

Default

<primer-card-form>
  <primer-input-cvv></primer-input-cvv>
</primer-card-form>

Custom Labels

<primer-input-cvv
  label="Security Code"
  placeholder="CVV"
  aria-label="Card security code"
></primer-input-cvv>

Inline with Expiry

<div style="display: flex; gap: 8px;">
  <primer-input-card-expiry></primer-input-card-expiry>
  <primer-input-cvv></primer-input-cvv>
</div>

Properties

Property	Attribute	Type	Default	Description
`label`	`label`	`string`	`"CVV"`	Label text
`placeholder`	`placeholder`	`string`	`"123"`	Placeholder text
`ariaLabel`	`aria-label`	`string`	Value of `label`	Screen reader label

Validation

Validates:

Required digits entered (3 for most networks, 4 for Amex)
Only numeric characters

Errors display automatically on submit or blur.

Dynamic Length (Amex)

The CVV field automatically adapts based on the card network detected by <primer-input-card-number>:

Network	CVV length	Default placeholder
Visa, Mastercard, Discover	3 digits	`123`
Amex	4 digits	`1234`

No configuration needed — length adjusts when the card number identifies the network.

Events

<primer-input-cvv> 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 input is invalid, 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

Reacting to card validation errors

const cardForm = document.querySelector('primer-card-form');

cardForm.addEventListener('primer:card-error', (event) => {
  const { errors } = event.detail;
  errors.forEach(err => console.log(err.field, err.message));
});

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	Valid CVV entered	Standard appearance
Error	Invalid CVV length	Red border, error message below
Disabled	Form or input disabled	Muted colors, no interaction

Usage Guidelines

Do

Place inside <primer-card-form>
Pair with <primer-input-card-expiry> in a flex row

Don’t

Don’t place outside card form context

Content Guidelines

Label

Do	Don’t
”CVV” (universally recognized)	“Card Verification Value” (too technical)
“Security code” (accessible alternative)	“CVC” without also accepting “CVV” as an alias

Placeholder

Do	Don’t
`123` (shows expected length)	“Enter CVV” (redundant with label)
`1234` when Amex is detected (4 digits)	Always showing 3-digit placeholder regardless of card network

Error messages

Do	Don’t
”Enter your card’s security code"	"Invalid"
"CVV is incomplete"	"Wrong CVV” (you can’t know if it’s wrong client-side)

primer-card-form

Parent container

primer-input-card-expiry

Expiry input

primer-input-card-number

Card number input

Web

<primer-input-cvv>

Quick Reference

Examples

Default

Custom Labels

Inline with Expiry

Properties

Validation

Dynamic Length (Amex)

Events

Relevant Parent Events

Reacting to card validation errors

CSS Properties

Typography

Colors

Border & Background

Spacing

Animation

States

Usage Guidelines

Do

Don’t

Content Guidelines

Label

Placeholder

Error messages

See also

primer-card-form

primer-input-card-expiry

primer-input-card-number

​<primer-input-cvv>

​Quick Reference

​Examples

​Default

​Custom Labels

​Inline with Expiry

​Properties

​Validation

​Dynamic Length (Amex)

​Events

​Relevant Parent Events

​Reacting to card validation errors

​CSS Properties

​Typography

​Colors

​Border & Background

​Spacing

​Animation

​States

​Usage Guidelines

​Do

​Don’t

​Content Guidelines

​Label

​Placeholder

​Error messages

​See also

primer-card-form

primer-input-card-expiry

primer-input-card-number

<primer-input-cvv>

Quick Reference

Examples

Default

Custom Labels

Inline with Expiry

Properties

Validation

Dynamic Length (Amex)

Events

Relevant Parent Events

Reacting to card validation errors

CSS Properties

Typography

Colors

Border & Background

Spacing

Animation

States

Usage Guidelines

Do

Don’t

Content Guidelines

Label

Placeholder

Error messages

See also