Skip to main content

​
<primer-billing-address>

Collects customer billing address during card payment flows. Validates based on your Dashboard configuration.

​
Quick Reference

Parent<primer-card-form>
RequiresDashboard configuration
PropertiesNone

​
Examples

​
In Custom Layout

<primer-card-form>
  <div slot="card-form-content">
    <primer-billing-address></primer-billing-address>
    <primer-input-card-holder-name></primer-input-card-holder-name>
    <primer-input-card-number></primer-input-card-number>
    <primer-input-card-expiry></primer-input-card-expiry>
    <primer-input-cvv></primer-input-cvv>
    <primer-card-form-submit>Pay</primer-card-form-submit>
  </div>
</primer-card-form>

​
Configuration

Configure in your Primer Dashboard:
  • Required vs optional fields
  • Validation rules
  • Country restrictions
  • Field display order
See Capturing Billing Address for setup.
Note: Component only renders if enabled in Dashboard.

​
Modes

ModeBehavior
Drop-inAutomatically included if Dashboard enabled
Custom layoutMust be explicitly added in card-form-content slot

​
Events

<primer-billing-address> does not emit its own events. Validation is triggered by the parent <primer-card-form> during submission.

​
Relevant Parent Events

EventEmitted byHow it affects this component
primer:card-submit<primer-card-form-submit> or external dispatchTriggers validation of all billing address fields — invalid fields display error messages
primer:card-error<primer-card-form>Emitted when any card or billing field fails validation — payload includes all validation errors
primer:card-success<primer-card-form>Emitted when the form (including billing address) submits successfully

​
CSS Properties

PropertyDescription
--primer-space-smallTitle bottom margin
--primer-space-mediumGap between fields
--primer-space-largeTitle top margin
--primer-color-text-primaryTitle color

​
States

StateDescriptionVisual Change
HiddenNot enabled in DashboardNot rendered
DefaultReady for inputStandard input appearance
FilledAddress enteredStandard appearance
ErrorValidation failedError states on invalid fields
DisabledForm disabledAll fields disabled

​
Usage Guidelines

​
Do

  • Place inside <primer-card-form>
  • Configure required fields in Dashboard
  • Enable in Dashboard before using

​
Don’t

  • Don’t expect rendering without Dashboard configuration
  • Don’t place outside card form context

​
Content Guidelines

​
Labels

DoDon’t
”Address line 1""Street address” (not universal)
“City""Town/City” (pick one per locale)
“Postal code” or “ZIP code” (locale-aware)“Zip” (informal)

​
International considerations

DoDon’t
Use locale-appropriate field labelsHard-code US-centric labels like “State” for all regions
Let the SDK adapt field order by countryForce a single address format globally

​
Error messages

DoDon’t
”Enter your billing address""Required"
"Enter a valid postal code""Invalid format”