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.
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 |
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
- 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) |
See also
primer-card-form
Parent container
primer-input-card-expiry
Expiry input
primer-input-card-number
Card number input
