Toast <va-toast>
Shows short status messages, such as "Changes saved", without interrupting the user.
When to use it
- Use it
- To confirm that something happened, such as "Changes saved" or "Link copied", or to report a background failure.
- Don't use it
- For anything the user must act on or read in full, or for form validation errors.
- Use instead
va-dialog for decisions; va-text-field's error for field errors.
Examples
Status messages
Place one va-toast per page. A va-button with commandfor and command="--show" sends its value as the message; data-variant sets the look.
Save
Copy link
Simulate an error
<va-button commandfor="toaster" command="--show" value="Changes saved" data-variant="success">Save</va-button>
<va-button variant="secondary" commandfor="toaster" command="--show" value="Link copied">Copy link</va-button>
<va-button variant="danger" commandfor="toaster" command="--show" value="Couldn't sync. Check your connection." data-variant="error">Simulate an error</va-button>
<va-toast id="toaster"></va-toast>
Install and import
npm install @firstprateek/vastu @firstprateek/vastu-tokens
import '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/toast';
API
Attributes and properties
| Attribute | Property | Type | Default | Description |
|---|
duration | duration | number | 5000 | Milliseconds before an info or success message closes by itself. Errors stay until dismissed. |
label | label | string | 'Notifications' | Accessible name of the region. |
| — | open (read-only) | boolean | — | True while at least one message is showing. |
Events
| Event | Description |
|---|
va-close | When a message closes. event.detail.reason is timeout, dismiss, escape or method. |
Methods
| Method | Description |
|---|
show(message, options) | Shows a message and returns its id. variant defaults to info; errors stay until dismissed. |
dismiss(id) | Closes one message by id, or every message when no id is given. |
Styling
Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.
| Custom property | Type | Description |
|---|
--va-toast-bg | <color> | Background colour of a message. |
--va-toast-fg | <color> | Text colour of a message. |
--va-toast-radius | <length> | Corner radius of a message. |
| Part | Description |
|---|
::part(region) | The fixed area the toasts appear in. |
::part(toast) | Each message. |
::part(dismiss) | Each message's dismiss button. |
Accessibility
- Role
status- Accessible name
- The
label attribute, "Notifications" by default. - Note
- Info and success messages are announced politely; errors use
role="alert" and are announced at once. - Note
- Messages pause their timer while hovered or focused, and errors stay until dismissed (WCAG 2.2.1).
Keyboard
| Key | Does |
|---|
| Escape | Dismisses the message that has focus. |
Every row on this page is checked by contract tests generated from the same manifest, in Chromium, Firefox and WebKit. Read the manifest.