> ## 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](/checkout/capture-billing-address) 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

<CardGroup cols={2}>
  <Card title="primer-card-form" icon="credit-card" href="/sdk/primer-checkout-web/components/primer-card-form/primer-card-form">
    Parent container
  </Card>

  <Card title="Capturing billing address" icon="location-dot" href="/checkout/capture-billing-address">
    Dashboard setup
  </Card>
</CardGroup>