Skip to main content

​
<primer-input-cvv>

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

​
Quick Reference

Parent<primer-card-form>
Propertieslabel, placeholder, aria-label
FeaturesSecure 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

PropertyAttributeTypeDefaultDescription
labellabelstring"CVV"Label text
placeholderplaceholderstring"123"Placeholder text
ariaLabelaria-labelstringValue of labelScreen 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>:
NetworkCVV lengthDefault placeholder
Visa, Mastercard, Discover3 digits123
Amex4 digits1234
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

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

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
FilledValid CVV enteredStandard appearance
ErrorInvalid CVV lengthRed border, error message below
DisabledForm or input disabledMuted 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

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

​
Placeholder

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

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