> ## 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.

# Billing Address

> Collects billing address information for card payments.

## \<primer-billing-address>

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

## Quick Reference

| | |
| - | - |
| **Parent** | `<primer-card-form>` |
| **Requires** | Dashboard configuration |
| **Properties** | None |

***

## Examples

### In Custom Layout

```html theme={"dark"}
<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](https://primer.io/docs/checkout/capture-billing-address.md) for setup.

> **Note:** Component only renders if enabled in Dashboard.

***

## Modes

| Mode | Behavior |
| - | - |
| **Drop-in** | Automatically included if Dashboard enabled |
| **Custom layout** | Must 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

| Event | Emitted by | How it affects this component |
| - | - | - |
| `primer:card-submit` | `<primer-card-form-submit>` or external dispatch | Triggers 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

| Property | Description |
| - | - |
| `--primer-space-small` | Title bottom margin |
| `--primer-space-medium` | Gap between fields |
| `--primer-space-large` | Title top margin |
| `--primer-color-text-primary` | Title color |

***

## States

| State | Description | Visual Change |
| - | - | - |
| **Hidden** | Not enabled in Dashboard | Not rendered |
| **Default** | Ready for input | Standard input appearance |
| **Filled** | Address entered | Standard appearance |
| **Error** | Validation failed | Error states on invalid fields |
| **Disabled** | Form disabled | All 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

| Do | Don'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

| Do | Don't |
| - | - |
| Use locale-appropriate field labels | Hard-code US-centric labels like "State" for all regions |
| Let the SDK adapt field order by country | Force a single address format globally |

### Error messages

| Do | Don't |
| - | - |
| "Enter your billing address" | "Required" |
| "Enter a valid postal code" | "Invalid format" |

***

## See also

> [card] [primer-card-form](https://primer.io/docs/sdk/primer-checkout-web/components/primer-card-form/primer-card-form.md)
>
> Parent container

> [card] [Capturing billing address](https://primer.io/docs/checkout/capture-billing-address.md)
>
> Dashboard setup


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.