Container for card payment inputs. Provides context to child components, handles validation, and manages form submission. Uses secure iframes for PCI compliance.
Quick Reference
| |
|---|
| Parent | <primer-checkout> |
| Properties | disabled, hide-labels |
| Slot | card-form-content |
| Emits | primer:card-success, primer:card-error |
| Listens for | primer:card-submit |
Examples
Default Layout
Renders all card inputs automatically:
<primer-card-form></primer-card-form>
Disabled State
<primer-card-form disabled></primer-card-form>
Hidden Labels
<primer-card-form hide-labels></primer-card-form>
Custom Layout
<primer-card-form>
<div slot="card-form-content">
<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>
<primer-input-card-holder-name></primer-input-card-holder-name>
<button type="submit">Pay Now</button>
</div>
</primer-card-form>
With Error Container
<primer-card-form>
<div slot="card-form-content">
<primer-input-card-number></primer-input-card-number>
<primer-input-card-expiry></primer-input-card-expiry>
<primer-input-cvv></primer-input-cvv>
<primer-error-message-container></primer-error-message-container>
<primer-card-form-submit></primer-card-form-submit>
</div>
</primer-card-form>
Properties
| Property | Attribute | Type | Default | Description |
|---|
disabled | disabled | boolean | false | Prevents form submission |
hideLabels | hide-labels | boolean | false | Hides labels on all inputs |
Events
Emitted Events
| Event | Description | Payload |
|---|
primer:card-success | Form submitted successfully | { result: unknown } |
primer:card-error | Validation errors occurred | { errors: ValidationError[] } |
Listened Events
| Event | Description |
|---|
primer:card-submit | Triggers form submission |
document.getElementById('my-button').addEventListener('click', () => {
document.dispatchEvent(
new CustomEvent('primer:card-submit', {
bubbles: true,
composed: true
})
);
});
Note: bubbles: true and composed: true are required for shadow DOM traversal.
Slots
| Slot | Description |
|---|
card-form-content | Custom layout for card inputs. Replaces default when provided. |
Methods
| Method | Description |
|---|
submit() | Programmatically submit the form |
const cardForm = document.querySelector('primer-card-form');
await cardForm.submit();
CSS Properties
| Property | Description | Default |
|---|
--primer-space-small | Gap between inline elements | 8px |
--primer-space-medium | Gap between block elements | 16px |
Dependencies
Internally uses:
Cardholder Name Configuration
checkout.options = {
card: {
cardholderName: {
visible: true, // Show field (default: true)
required: true, // Make required (default: true)
defaultValue: '' // Pre-fill value
}
}
};
Co-branded Card Schemes
Supports co-branded cards like Cartes Bancaires (CB). Network switcher displays automatically when detected. No configuration needed.
Submit Options
| Method | Example |
|---|
<primer-card-form-submit> | Built-in, localized |
<button type="submit"> | Standard HTML |
<primer-button type="submit"> | Primer button |
data-submit attribute | Any element |
primer:card-submit event | Programmatic |
Validation
- Validates all inputs on submission
- If invalid, dispatches
primer:card-error
- Child inputs display error messages
- If valid, proceeds with payment
States
| State | Description | Visual Change |
|---|
| Ready | Form ready for input | All inputs enabled |
| Validating | Validation in progress | Inputs may show loading |
| Valid | All inputs pass validation | Submit button enabled |
| Invalid | One or more validation errors | Error states on inputs |
| Submitting | Payment being processed | Inputs disabled, button loading |
| Disabled | disabled attribute set | All inputs disabled, muted appearance |
Usage Guidelines
- Place all card inputs inside
<primer-card-form>
- Include
<primer-error-message-container> for payment failures
- Use
primer:card-submit event for external submit buttons
- Configure cardholder name via SDK options
Don’t
- Don’t use alongside
<primer-payment-method type="PAYMENT_CARD"> (causes duplicates)
- Don’t place card inputs outside the form
- Don’t use multiple card forms on one page
Using both <primer-card-form> and <primer-payment-method type="PAYMENT_CARD"> in the same layout creates duplicate card forms. Choose one approach.
Content Guidelines
Submit button text
| Do | Don’t |
|---|
| ”Pay now" | "Submit" |
| "Complete payment" | "Pay" |
| "Pay $49.99" | "OK” |
Error messages
| Do | Don’t |
|---|
| ”Card number is invalid" | "Error" |
| "Card has expired" | "Invalid input” |
