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

> [card] [Error handling guide](https://primer.io/docs/checkout/primer-checkout/build-your-ui/error-handling.md)
>
> Custom error patterns

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


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