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.
<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
<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
<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
- 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:
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
Error handling guide
Custom error patterns
primer-card-form
Card validation
