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
- Theme previews
Installation
- npm
- Yarn
npm install @rcarls/rc-snackbar
yarn add @rcarls/rc-snackbar
import '@rcarls/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
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. |
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. |
Slots
No slots are documented in the custom elements manifest.
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. |