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-labelsSlot card-form-contentEmits primer:card-success, primer:card-errorListens for primer:card-submit
Examples Default layout Renders all card inputs automatically:
< primer-card-form ></ primer-card-form >
Renders: Card number, expiry, CVV, cardholder name, and submit button.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 disableddisabledbooleanfalsePrevents form submission hideLabelshide-labelsbooleanfalseHides labels on all inputs
Events Emitted events Event Description Payload primer:card-successForm submitted successfully { result: unknown }primer:card-errorValidation errors occurred { errors: ValidationError[] }
Listened events Event Description primer:card-submitTriggers form submission
External submit example: 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-contentCustom 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-smallGap between inline elements 8px--primer-space-mediumGap 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 attributeAny element primer:card-submit eventProgrammatic
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 setAll 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”
See also
Build custom card form Step-by-step guide
Troubleshooting Common issues and solutions
Events guide Event handling
