<primer-checkout> The root container for all Primer payment components. Initializes the SDK, manages checkout state, and provides context to child components. Use as a drop-in solution or customize fully.
Quick reference Properties client-token (required), options, custom-styles, loader-disabledSlot mainEmits primer:ready, primer:state-change, primer:methods-update, primer:payment-success, primer:payment-failureListens for primer:card-submit, primer:vault-submit
Examples Drop-in (minimal) < primer-checkout client-token = "your-client-token" ></ primer-checkout >
Automatically displays all configured payment methods with default styling.
With primer-main < primer-checkout client-token = "your-client-token" > < primer-main slot = "main" > < div slot = "payments" > < primer-payment-method type = "PAYMENT_CARD" ></ primer-payment-method > < primer-payment-method type = "PAYPAL" ></ primer-payment-method > </ div > < div slot = "checkout-complete" > < h2 > Thank you for your purchase! </ h2 > </ div > </ primer-main > </ primer-checkout >
Fully custom < primer-checkout client-token = "your-client-token" > < div slot = "main" id = "custom-checkout" > < h2 > Select Payment Method </ h2 > < primer-payment-method type = "PAYMENT_CARD" ></ primer-payment-method > < primer-error-message-container ></ primer-error-message-container > </ div > </ primer-checkout >
Note: Without <primer-main>, you must handle state changes via events.
With options // Set options via JavaScript (recommended) const checkout = document . querySelector ( 'primer-checkout' ); checkout . setAttribute ( 'client-token' , 'your-client-token' ); checkout . options = { locale: 'en-GB' , card: { cardholderName: { required: true } } };
Note: Always set options via direct JavaScript assignment, not via setAttribute(). HTML attributes are only appropriate for simple string values like client-token.
With custom styling < primer-checkout client-token = "your-client-token" custom-styles = '{"primerColorBrand":"#4a6cf7"}' ></ primer-checkout >
Dark theme < primer-checkout client-token = "your-client-token" class = "primer-dark-theme" > </ primer-checkout >
Properties Property Attribute Type Default Description clientTokenclient-tokenstring''Required. Client token from your backendoptionsoptionsobject{}SDK configuration options customStylescustom-stylesstring''JSON string of CSS variables loaderDisabledloader-disabledbooleanfalseDisables the default loading spinner
Setting properties const checkout = document . querySelector ( 'primer-checkout' ); // Use setAttribute for string/boolean attributes checkout . setAttribute ( 'client-token' , 'your-token' ); checkout . setAttribute ( 'custom-styles' , JSON . stringify ({ primerColorBrand: '#4a6cf7' })); checkout . setAttribute ( 'loader-disabled' , 'true' ); // Use direct assignment for options object checkout . options = { locale: 'en-GB' };
Important: Use setAttribute() for client-token, custom-styles, and loader-disabled. Use direct property assignment for options.
Events Emitted events Event When Payload primer:readySDK initialized PrimerJS instanceprimer:state-changeCheckout state changes { isLoading, isProcessing, isSuccessful, paymentFailure, primerJsError }primer:methods-updatePayment methods loaded InitializedPaymentMethod[]primer:payment-successPayment completed { payment, paymentMethodType, timestamp }primer:payment-failurePayment failed { error, payment?, paymentMethodType, timestamp }
Listened events Event Purpose primer:card-submitTriggers card form submission primer:vault-submitTriggers vault payment submission
Event handling example const checkout = document . querySelector ( 'primer-checkout' ); checkout . addEventListener ( 'primer:payment-success' , ( event ) => { const { payment } = event . detail ; window . location . href = `/confirmation?order= ${ payment . orderId } ` ; }); checkout . addEventListener ( 'primer:payment-failure' , ( event ) => { const { error } = event . detail ; console . error ( 'Payment failed:' , error . diagnosticsId ); }); checkout . addEventListener ( 'primer:state-change' , ( event ) => { const { isProcessing , isSuccessful , paymentFailure } = event . detail ; // Update your UI based on state });
Slots Slot Description mainMain content area. Defaults to <primer-main> with all payment methods if not provided.
CSS properties Style via CSS variables or the custom-styles attribute:
primer-checkout { --primer-color-brand : #4a6cf7 ; --primer-radius-base : 4px ; --primer-typography-brand : 'Inter' , sans-serif ; }
See Styling Variables Reference for all available properties.
Dependencies This component is the parent for:
Component Purpose primer-main State management and slots primer-payment-method Individual payment methods primer-card-form Card payment form primer-vault-manager Saved payment methods
States State Description Loading SDK initializing Ready SDK ready, payment methods available Processing Payment in progress Success Payment completed Failure Payment failed Error SDK initialization failed
Usage guidelines
Provide a valid client-token from your backend
Listen for primer:payment-success and primer:payment-failure to handle outcomes
Handle both success and failure states
Use <primer-error-message-container> for payment failures
Don’t
Don’t use multiple <primer-checkout> instances (single instance per page)
Don’t set options via setAttribute() — use direct assignment
Don’t call SDK methods before primer:ready fires
Only use a single <primer-checkout> instance per page. Multiple instances will cause initialization conflicts and unpredictable behavior.
Localization checkout . options = { locale: 'fr-FR' };
See Localization Guide for supported locales. Falls back to en-GB if unsupported.
Note: Only left-to-right (LTR) languages are currently supported.
Content guidelines Loading state Do Don’t Show a spinner or skeleton without text ”Loading checkout…” Keep the container height stable to prevent layout shift Collapse the container to zero height
Error messages (default experience) Do Don’t Let the SDK display its built-in, localized messages Override SDK errors with generic text like “Something went wrong” Supplement with a retry prompt: “Please try again or use a different method” Show raw error codes to customers
See also
SDK options reference All configuration options
Events guide Event handling patterns
Styling variables CSS customization
Installation Getting started
