<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
With Custom Layout
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
paymentFailurestate 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: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 |
Related
- Error Handling Guide — Custom error patterns
- primer-card-form — Card validation