mielui
Blocks

Toast

A notification that stacks, auto-dismisses, and can carry an action.

Installation

pnpm dlx @mielui/svelte add toast

Usage

Mount one Toaster in your root layout. The first mounted Toaster shows every notification, so do not add a second one.

<script lang="ts">
    import { Toaster } from '@mielui/svelte/components/toast';

    let { children } = $props();
</script>

{@render children()}
<Toaster />

Then call toast from anywhere. toast.success, toast.error, toast.warning, toast.info, and toast.loading set the type for you. Each call returns a handle, and toast.dismiss(id) closes one notification, or all of them without an id.

<script lang="ts">
    import { Button } from '@mielui/svelte/components/button';
    import { toast } from '@mielui/svelte/components/toast';

    function save() {
        toast.success('Profile updated', {
            description: 'Your changes have been saved.'
        });
    }
</script>

<Button onclick={save}>Save</Button>

Notifications close after duration milliseconds, 5600 by default, and pause while hovered or focused. Set persistent: true for a notification that should wait for the user, and exitable: false to hide its close button.

Composition

Toast.Root renders one toast object. Without children it renders Content, Footer, Icon, Title, Actions, and Close. Compose those parts to leave out, reorder, or restyle a region. Title and Content show the toast title and description unless you pass children, and Actions renders the configured actions or your own Toast.Action parts. Toast.Root on its own starts no timer; Toaster does that for notifications created with toast.

Examples

Follow-up toast

The action on the first toast opens a second one with the details.

Actions

Each action takes a label, a callback, and an optional button variant, outline by default. Clicking one runs the callback and closes the toast.

Promise

toast.promise shows one notification that updates as the promise settles. The success and error messages can be functions of the result or the error. It returns the toast handle, so await the original promise when later work depends on it.

Types

Glass surface

Pass surface: 'glass' to toast, or set surface on Toast.Root. The glass surface falls back to an opaque one when backdrop filters are unavailable or reduced transparency is on.

Notch

variant="notch" on Toaster delivers notifications from the middle of a screen edge, chosen with side. toast and toast.promise work the same way. The newest notification shows first. With several active, previous and next buttons unfold beside the notch on hover or focus. Escape or a swipe toward the edge dismisses the selected one. Use this Toaster in place of your existing one. For custom live activity, compose the Notch component directly.

Labels

Built-in text is English. Pass a labels object to Toaster to translate the name of the notifications region, the dismiss button, and the notch previous, next, and position controls. count is the visible notch counter, such as 2 of 5; it is a function so a translation can place both numbers. ToastLabels types it. Every key is optional, and omitted keys keep their English default.

<Toaster
    labels={{
        region: 'Notifications',
        dismiss: 'Fermer',
        previous: 'Précédente',
        next: 'Suivante',
        position: (position, total) => `Notification ${position} sur ${total}`,
        count: (index, total) => `${index} sur ${total}`
    }}
/>

API reference

Toast.Root

Owns one notification and pauses its timer during interaction.

  • toast Required
    Toast

    Toast data from the store.

  • surface
    "solid" | "glass"

    Surface treatment. Omit it to inherit --mielui-surface from the theme.

    Default toast.surface

Toast.Action

Runs one action and dismisses the toast.

  • action Required
    ToastAction

    Label and handler for the action.

Toaster

Renders the notification region.

  • variant
    "default" | "notch"

    notch presents toasts as a Notch attached to an edge.

    Default 'default'

  • side
    "top" | "bottom" | "left" | "right"

    Viewport edge toasts appear from.

    Default 'top'

  • labels
    ToastLabels

    Overrides the built-in text and accessible names. Every key is optional and English is the fallback.

Other parts

These parts have no props of their own. They pass HTML attributes and events to their element.

  • Toast.Actions Groups action buttons.
  • Toast.Close Dismisses the notification.
  • Toast.Content Renders the inset with the title and description.
  • Toast.Footer Groups the action buttons on the frame.
  • Toast.Icon Renders the status icon.
  • Toast.Title Renders the notification title.