Transient messages with tone, a leading slot, and screen position.
Also known as: snackbar, notification toast, toast message, toast notification
Install with the CLI, or copy the component source into your project.
Add toast (npm)
1npx --yes -p @default-file/ui df-ui add toast
Default success, error, info, and warning cards. Each tone sets the accent and the default leading icon.
Saved successfully
Something went wrong
Heads up
Check this value
Pass leading to replace the tone icon with any node, or null to hide the slot. Custom icons inherit the tone accent through currentColor unless you set a color.
Export ready for download
Custom mark in the leading slot
Message only, no leading
Tune fill, border, shadow, radius, padding block and inline, inner gap, width, height, and close visibility with props or --df-toast-* variables. Stack gap and width use --df-toaster-* on Toaster.
Roomier padding and softer shadow
Custom fill, border, and no close
Fixed min height
Place live toasts in any corner, along an edge centre, or dead centre. Use the direction pad to try each spot.
Active: Bottom right
Transient messages. Render Toast for static chrome, or mount Toaster once and call toast helpers for live messages. Tune chrome with props or --df-toast-* / --df-toaster-* CSS variables.
Presentational toast card. Toaster renders the same chrome for live messages.
| Prop | Type | Default | Notes |
|---|---|---|---|
| tone | "success" | "error" | "info" | "warning" | - | Accent for the leading icon. Also selects the default leading icon when leading is omitted. |
| message | string | - | Primary toast copy. |
| leading | ReactNode | - | Leading slot before the message. Defaults to the tone icon. Pass a custom icon or node to replace it, or null to hide the slot. Custom icons inherit the tone accent through currentColor unless you set a color. |
| onDismiss | () => void | - | When set, renders an interactive dismiss control. Omit for static chrome with a non-interactive close glyph when showClose is true. |
| background | string | - | Card fill. Sets --df-toast-bg. |
| foreground | string | - | Card text color. Sets --df-toast-fg. |
| borderColor | string | - | Card border color. Sets --df-toast-border. |
| borderWidth | string | - | Card border width. Sets --df-toast-border-width. |
| radius | string | - | Card corner radius. Sets --df-toast-radius. |
| shadow | string | - | Card box shadow. Sets --df-toast-shadow. |
| paddingBlock | string | - | Top and bottom padding. Sets --df-toast-padding-block. |
| paddingInline | string | - | Left and right padding. Sets --df-toast-padding-inline. |
| gap | string | - | Gap between leading, message, and close. Sets --df-toast-gap. |
| width | string | - | Card width. Sets --df-toast-width. Default 100% of the stack. |
| height | string | - | Card height. Sets --df-toast-height. Default auto. |
| minHeight | string | - | Card minimum height. Sets --df-toast-min-height. |
| showClose | boolean | true | Show the close control. Set false to hide it. |
| cornerShape | "round" | "smooth" | - | Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init). |
| className | string | - | Additional styles on the toast root. |
| style | CSSProperties | - | Inline styles. Merged after chrome props. Prefer chrome props or --df-toast-* variables. |
Portal host for live toasts. Mount once near the app root. Live toasts auto-dismiss after 3200ms. Card chrome props on Toaster inherit to every toast in the stack.
| Prop | Type | Default | Notes |
|---|---|---|---|
| position | "top-left" | "top-center" | "top-right" | "left-center" | "center" | "right-center" | "bottom-left" | "bottom-center" | "bottom-right" | "bottom-right" | Screen corner, edge centre, or dead centre for the stack. |
| stackWidth | string | - | Stack width. Sets --df-toaster-width. |
| stackGap | string | - | Gap between stacked toasts. Sets --df-toaster-gap. |
| inset | string | - | Distance from the viewport edge. Sets --df-toaster-inset. |
| viewportGutter | string | - | Horizontal viewport reserve used in the stack max-width clamp. Sets --df-toaster-viewport-gutter. |
| background | string | - | Card fill. Sets --df-toast-bg. |
| foreground | string | - | Card text color. Sets --df-toast-fg. |
| borderColor | string | - | Card border color. Sets --df-toast-border. |
| borderWidth | string | - | Card border width. Sets --df-toast-border-width. |
| radius | string | - | Card corner radius. Sets --df-toast-radius. |
| shadow | string | - | Card box shadow. Sets --df-toast-shadow. |
| paddingBlock | string | - | Top and bottom padding. Sets --df-toast-padding-block. |
| paddingInline | string | - | Left and right padding. Sets --df-toast-padding-inline. |
| gap | string | - | Gap between leading, message, and close. Sets --df-toast-gap. |
| width | string | - | Card width. Sets --df-toast-width. Default 100% of the stack. |
| height | string | - | Card height. Sets --df-toast-height. Default auto. |
| minHeight | string | - | Card minimum height. Sets --df-toast-min-height. |
| showClose | boolean | true | Show the close control. Set false to hide it. |
| cornerShape | "round" | "smooth" | - | Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init). |
| className | string | - | Additional styles on the toaster root. |
| style | CSSProperties | - | Inline styles on the toaster root. Merged after stack and chrome props. |
Imperative helpers for showing and dismissing live toasts. Requires a mounted Toaster.
| Prop | Type | Default | Notes |
|---|---|---|---|
| toast.success | (message: string, options?: ToastShowOptions) => string | - | Show a success toast. Returns the toast id. |
| toast.error | (message: string, options?: ToastShowOptions) => string | - | Show an error toast. Returns the toast id. |
| toast.info | (message: string, options?: ToastShowOptions) => string | - | Show an info toast. Returns the toast id. |
| toast.warning | (message: string, options?: ToastShowOptions) => string | - | Show a warning toast. Returns the toast id. |
| toast.dismiss | (id?: string) => void | - | Dismiss one toast by id, or all toasts when id is omitted. |
| setToastPosition | (position: ToastPosition) => void | - | Update where new and existing live toasts stack. Same values as Toaster position. |
Optional second argument to toast.success, toast.error, toast.info, and toast.warning.
| Prop | Type | Default | Notes |
|---|---|---|---|
| leading | ReactNode | - | Same contract as Toast leading. Replaces the tone icon, or null to hide the slot. |
Theme defaults live on :root. Override globally, on Toaster (inherits to the stack), or on Toast. Chrome props set the matching variables.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-toaster-width | CSS length | 22rem | Toaster stack width. |
| --df-toaster-gap | CSS length | calc(2 * var(--spacing-unit)) | Gap between stacked toasts. |
| --df-toaster-inset | CSS length | calc(4 * var(--spacing-unit)) | Distance from the viewport edge. |
| --df-toaster-viewport-gutter | CSS length | calc(8 * var(--spacing-unit)) | Horizontal viewport reserve for the stack max-width clamp. |
| --z-toast | number | 60 | Stack layer above overlays. |
| --df-toast-width | CSS length | 100% | Toast card width. |
| --df-toast-height | CSS length | auto | Toast card height. |
| --df-toast-min-height | CSS length | auto | Toast card minimum height. |
| --df-toast-bg | CSS color | var(--popover) | Toast fill. |
| --df-toast-fg | CSS color | var(--popover-foreground) | Toast text color. |
| --df-toast-border | CSS color | var(--border) | Toast border color. |
| --df-toast-border-width | CSS length | var(--border-width-hairline) | Toast border width. |
| --df-toast-radius | CSS length | var(--radius) | Toast corner radius. |
| --df-toast-shadow | CSS shadow | var(--df-shadow-lg) | Toast box shadow. |
| --df-toast-padding-block | CSS length | calc(3 * var(--spacing-unit)) | Top and bottom padding. |
| --df-toast-padding-inline | CSS length | calc(3.5 * var(--spacing-unit)) | Left and right padding. |
| --df-toast-gap | CSS length | calc(2.5 * var(--spacing-unit)) | Gap between leading, message, and close. |
| --df-toast-icon-success | CSS color | var(--success) | Success tone icon accent. |
| --df-toast-icon-error | CSS color | var(--destructive) | Error tone icon accent. |
| --df-toast-icon-warning | CSS color | var(--warning) | Warning tone icon accent. |
| --df-toast-icon-info | CSS color | var(--muted-foreground) | Info tone icon accent. |
| --df-toast-close-size | CSS length | var(--df-control-height-2xs) | Close control width and height. |
| --df-toast-close-fg | CSS color | var(--muted-foreground) | Close control icon color. |
| --df-toast-close-hover-bg | CSS color | var(--muted) | Close control hover fill. |
| --df-toast-close-hover-fg | CSS color | var(--foreground) | Close control hover icon color. |
| --df-corner-shape | CSS corner-shape | var(--df-corner-shape-round) | Theme corner curve for all kit chrome. round = circular arcs; smooth = continuous squircle. Set with df-ui init --corner-shape, or override on :root. Default round. |