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

# Error Message Container

> Automatically displays payment failure errors.

## \<primer-error-message-container>

Displays payment failure errors automatically. Subscribes to SDK state and shows/hides error messages without custom code.

## Quick Reference

|                |                       |
| -------------- | --------------------- |
| **Parent**     | `<primer-checkout>`   |
| **Properties** | None                  |
| **Displays**   | Payment failures only |

***

## Examples

### Basic Usage

```html theme={"dark"}
<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-card-form></primer-card-form>
      <primer-error-message-container></primer-error-message-container>
    </div>
  </primer-main>
</primer-checkout>
```

### With Custom Layout

```html theme={"dark"}
<primer-checkout client-token="your-token">
  <div slot="main">
    <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
    <primer-error-message-container></primer-error-message-container>
  </div>
</primer-checkout>
```

***

## What It Displays

| Displays                            | Does Not Display           |
| ----------------------------------- | -------------------------- |
| Payment failures (after submission) | Card validation errors     |
| Declined transactions               | SDK initialization errors  |
| Processing errors                   | Network errors during load |

***

## Events

`<primer-error-message-container>` does not emit its own events. It subscribes to parent state internally to show and hide error messages.

### Relevant Parent Events

| Event                    | Emitted by          | How the container uses it                                                                            |
| ------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `primer:state-change`    | `<primer-checkout>` | Reads `paymentFailure` from the payload — shows the error message when populated, hides when cleared |
| `primer:payment-failure` | `<primer-checkout>` | Triggers the same display — the container reacts to the resulting state change                       |

***

## Behavior

* **Shows** when `paymentFailure` state is populated
* **Hides** when payment succeeds or user retries
* **Includes** ARIA attributes for accessibility

***

## CSS Properties

### Colors

| Property                               | Description            | Default   |
| -------------------------------------- | ---------------------- | --------- |
| `--primer-color-red-100`               | Error background color | `#ffecec` |
| `--primer-color-border-outlined-error` | Error border color     | `#ff7279` |
| `--primer-color-text-negative`         | Error text color       | `#b4324b` |
| `--primer-color-icon-negative`         | Error icon color       | `#ff7279` |

### Typography

| Property                                 | Description         | Default |
| ---------------------------------------- | ------------------- | ------- |
| `--primer-typography-body-medium-size`   | Message text size   | `14px`  |
| `--primer-typography-body-medium-weight` | Message text weight | `400`   |

### Spacing & Shape

| Property                 | Description      | Default |
| ------------------------ | ---------------- | ------- |
| `--primer-space-small`   | Internal padding | `8px`   |
| `--primer-space-medium`  | Icon-to-text gap | `12px`  |
| `--primer-radius-medium` | Border radius    | `8px`   |

### Animation

| Property                      | Description          | Default                         |
| ----------------------------- | -------------------- | ------------------------------- |
| `--primer-animation-duration` | Show/hide transition | `200ms`                         |
| `--primer-animation-easing`   | Transition easing    | `cubic-bezier(0.44, 0, 0.4, 1)` |

***

## States

| State         | Description                  | Visual Change                      |
| ------------- | ---------------------------- | ---------------------------------- |
| **Hidden**    | No payment failure           | Not visible (height: 0)            |
| **Visible**   | Payment failure occurred     | Error banner with icon and message |
| **Animating** | Transitioning between states | Fade/slide animation               |

***

## Usage Guidelines

### Do

* Include in any custom layout for error display
* Place near the payment form for visibility

### Don't

* Don't use for validation errors (handled by input components)
* Don't use if implementing custom error handling via events

***

## Alternative: Custom Error Handling

For full control, handle errors via events instead:

```javascript theme={"dark"}
checkout.addEventListener('primer:state-change', (event) => {
  const { paymentFailure } = event.detail;
  if (paymentFailure) {
    document.getElementById('my-error').textContent = paymentFailure.message;
  }
});
```

***

## Content Guidelines

### Error messages

| Do                                                          | Don't                          |
| ----------------------------------------------------------- | ------------------------------ |
| "Your payment could not be processed. Please try again."    | "Error 4001: DECLINED"         |
| "This payment method was declined. Try a different method." | "Transaction failed"           |
| Use plain language                                          | Expose error codes to the user |

### Tone

| Do                                | Don't                                       |
| --------------------------------- | ------------------------------------------- |
| Be reassuring: "Please try again" | Be blaming: "You entered the wrong details" |
| Suggest next steps                | Leave the user with no guidance             |

***

## See also

<CardGroup cols={2}>
  <Card title="Error handling guide" icon="triangle-exclamation" href="/checkout/primer-checkout/build-your-ui/error-handling">
    Custom error patterns
  </Card>

  <Card title="primer-card-form" icon="credit-card" href="/sdk/primer-checkout-web/components/primer-card-form/primer-card-form">
    Card validation
  </Card>
</CardGroup>