Sonner

Positioned toast viewport, shadcn's successor to the legacy toast primitive. Re-exports toast Props / Variant / render API for compatibility. Adds a Position enum (six placements) that drives viewport anchoring via data-position attribute. Brand-new v0.2.1 primitive.

Import

use maud_ui::primitives::sonner::{self, Position, Props, Variant};

Example

use maud::html;
use maud_ui::primitives::sonner;

html! {
    // Viewport placed at bottom-right (default)
    (sonner::viewport(sonner::Position::BottomRight))
    
    // Or with explicit id for multiple independent viewports
    (sonner::viewport_with_id("my-viewport", sonner::Position::TopRight))
    
    // Render a static toast for SSR or demo
    (sonner::toast(sonner::Props {
        variant: sonner::Variant::Success,
        title: "Saved".to_string(),
        description: Some("Your changes have been stored.".to_string()),
        duration_ms: 4000,
    }))
}

Props

Re-exported from toast. Refer to Toast documentation for complete Props details.

Position Enum

Helpers

viewport

sonner::viewport(position: Position) -> Markup

Renders the sonner viewport container at the given position. The element carries id="mui-sonner-viewport" so the behaviour file finds it without a selector walk.

viewport_with_id

sonner::viewport_with_id(id: &str, position: Position) -> Markup

Renders a sonner viewport with an explicit DOM id. Use this for pages needing multiple independent viewports (rare).

toast

sonner::toast(props: Props) -> Markup

Thin alias for render(props) mirroring shadcn's JS sonner.toast(...) spelling. Returns markup for a single toast node. For server-rendered static toasts, call this; for imperative dispatch, fire a mui:sonner-toast CustomEvent on window.

Variant Styles

Accessibility

• Viewport container has aria-live="polite" to announce new toasts to screen readers.
• Toast role is implicitly live-region-aware via the container.
• Toasts are announced in the order they appear; stale toasts fade silently.
• Title is the primary announcement; description is secondary.

CSS Classes

Behaviour

The companion JS behaviour (dist/behaviors/toast.js) handles:

• Listening for mui:sonner-toast CustomEvents on window.
• Creating new toast elements and injecting them into the viewport.
• Auto-dismissing after duration_ms.
• Reacting to viewport data-position changes (live theme switching in galleries).

Dispatching a toast from JS:

window.dispatchEvent(new CustomEvent('mui:sonner-toast', {
  detail: {
    variant: 'success',
    title: 'Saved',
    description: 'Your changes have been stored.',
    duration_ms: 4000
  }
}));

Related

Toast (legacy), Alert, Notification.

Shadcn reference

https://ui.shadcn.com/docs/components/base/sonner