rc-snackbar
rc-snackbar is a live-region host for brief status messages and optional actions.
- Package
@rcarls/rc-snackbar- Element
<rc-snackbar>- Native dependency
- Polite status live region
- State model
- Imperative message queue
- Main events
rc-snackbar-actionrc-snackbar-close- Related
- Usage rulesTheme previews
Installation
- npm
- Yarn
- pnpm
npm install @rcarls/rc-webcomponents@next
yarn add @rcarls/rc-webcomponents@next
pnpm add @rcarls/rc-webcomponents@next
import '@rcarls/rc-webcomponents/rc-snackbar/define';
Usage
<rc-snackbar id="snackbar"></rc-snackbar>
document.querySelector('#snackbar').show({
message: 'Document archived',
actionLabel: 'Undo',
duration: 5000,
});
rc-snackbar does not move focus. It announces through a polite status live region
and queues messages by default. Positive duration values auto-dismiss the
visible message; use 0 only when the application deliberately owns dismissal.
open reflects visibility and follows the library's controlled/uncontrolled
convention: host writes are silent, and default-open seeds an initial
visible state. show(), close(), and clear() remain the primary way to
drive the queue and timer; write open directly only for advanced cases that
don't need queueing, such as an initially visible component seeded from
server-rendered message/default-open attributes.
The theme-free surface uses system canvas colors and a plain border, while its action retains native button styling. Packaged themes provide the component's color, shape, spacing, and action treatment.
Live demo
Accessibility
Messages appear in a role="status" live region with aria-live="polite" and
aria-atomic="true", so screen readers announce them without moving focus. The action is a
native button. A positive duration closes the message on a timer that pauses while the
pointer is over the snackbar or focus is inside it, and resumes with the time that was left, so
people can reach the action (WCAG 2.2.1).
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
open | open | boolean | Not specified | Whether the snackbar is currently visible. Host writes are silent. |
defaultOpen | default-open | boolean | Not specified | Initial visible state for uncontrolled usage, such as an already-queued message shown on first render. |
message | message | string | '' | Visible message text. |
actionLabel | action-label | string | '' | Optional action button label. |
duration | duration | number | 4000 | Auto-close duration in milliseconds. Set to 0 to keep open. The timer pauses while the pointer is over the snackbar or focus is inside it. |
queuePolicy | queue-policy | RCSnackbarQueuePolicy | 'queue' | Queue behavior for show calls while open. |
Methods
| Method | Description |
|---|---|
show(message: string | RCSnackbarShowOptions) | Shows a message or queues it according to `queuePolicy`. |
close(reason: RCSnackbarCloseReason) | Closes the current snackbar. |
clear() | Clears the current snackbar and all queued messages. |
Events
| Event | Detail type | Description |
|---|---|---|
rc-snackbar-close | CustomEvent | Fired after a visible snackbar closes. |
rc-snackbar-action | CustomEvent | Fired when the action button is activated. |
CSS Custom Properties
| Property | Default | Description |
|---|---|---|
--rc-snackbar-inset-inline | 1rem | Inline-axis inset from the viewport edge. |
--rc-snackbar-inset-block-end | 1rem | Block-end inset from the viewport edge, before the safe-area inset. |
--rc-snackbar-z-index | 1000 | Stacking order. |
--rc-snackbar-gap | 0.5rem | Gap between the message and action. |
--rc-snackbar-min-block-size | 3rem | Minimum surface block size. |
--rc-snackbar-max-inline-size | 30rem | Maximum surface inline size. |
--rc-snackbar-padding-block | 0.5rem | Surface block-axis padding. |
--rc-snackbar-padding-inline | 1rem | Surface inline-axis padding. |
--rc-snackbar-border | 1px solid CanvasText | Surface border. |
--rc-snackbar-radius | 0 | Surface border radius. |
--rc-snackbar-bg | Canvas | Surface background. |
--rc-snackbar-color | CanvasText | Surface text color. |
--rc-snackbar-shadow | none | Surface box shadow. |
--rc-snackbar-action-border | Not specified | Action button border; defers to native button border when unset. |
--rc-snackbar-action-radius | Not specified | Action button border radius; defers to native button radius when unset. |
--rc-snackbar-action-padding-block | Not specified | Action button block-axis padding; defers to native button padding when unset. |
--rc-snackbar-action-padding-inline | Not specified | Action button inline-axis padding; defers to native button padding when unset. |
--rc-snackbar-action-bg | Not specified | Action button background; defers to native button background when unset. |
--rc-snackbar-action-color | Not specified | Action button text color; defers to native button color when unset. |
--rc-snackbar-action-font | Not specified | Action button font shorthand; defers to native button font when unset. |
--rc-snackbar-focus-ring | Not specified | Action button focus outline; defers to native focus styling when unset. |
--rc-snackbar-focus-ring-offset | Not specified | Action button focus outline offset; defers to native focus styling when unset. |
CSS Parts
| Part | Description |
|---|---|
surface | Snackbar surface. |
message | Message text. |
action | Optional action button. |