On this page

Toast Primitive

Toast is a Starwind Runtime primitive in the notification-system contract family. Astro, React, Vue, and Svelte components use the same underlying interactions. Each framework has its own way to read and update state. See the examples and your installed package’s types for the available props and events. Plain HTML uses DOM events and Runtime methods.

Anatomy

Use the Astro primitive adapter to render Toast anatomy with the Runtime wiring included.

---
import { Toast } from "@starwind-ui/astro/toast";
---

<Toast.Viewport>
  <Toast.Root>
    <Toast.Content>
      <Toast.Title>Saved</Toast.Title>
      <Toast.Description>Your changes were saved.</Toast.Description>
    </Toast.Content>
    <Toast.Close>Dismiss</Toast.Close>
  </Toast.Root>
</Toast.Viewport>

Use the React primitive adapter when Toast state participates in React rendering.

import { Toast } from "@starwind-ui/react/toast";

export function Example() {
  return (
    <Toast.Viewport>
      <Toast.Root>
        <Toast.Content>
          <Toast.Title>Saved</Toast.Title>
          <Toast.Description>Your changes were saved.</Toast.Description>
        </Toast.Content>
        <Toast.Close>Dismiss</Toast.Close>
      </Toast.Root>
    </Toast.Viewport>
  );
}

Use the Vue components to build Toast.

<script setup lang="ts">
import Toast from "@starwind-ui/vue/toast";
</script>

<template>
  <Toast.Viewport>
    <Toast.Root>
      <Toast.Content>
        <Toast.Title>Saved</Toast.Title>
        <Toast.Description>Your changes were saved.</Toast.Description>
      </Toast.Content>
      <Toast.Close>Dismiss</Toast.Close>
    </Toast.Root>
  </Toast.Viewport>
</template>

Render the Toast data-sw-* contract yourself, then initialize createToastManager.

<div data-sw-toast-viewport role="region" aria-live="polite" aria-atomic="false" aria-relevant="additions text" aria-label="Notifications" tabindex="-1">
  <div data-sw-toast-root>
    <div data-sw-toast-content>
      <div data-sw-toast-title>Saved</div>
      <div data-sw-toast-description>Your changes were saved.</div>
    </div>
    <button data-sw-toast-close type="button" aria-label="Close notification">Dismiss</button>
  </div>
</div>

<script type="module">
  import { createToastManager } from "@starwind-ui/runtime/toast";

  const root = document.querySelector("[data-sw-toast-viewport]");
  if (root) {
    createToastManager(root);
  }
</script>

API Reference

Viewport

The visible viewport for Toast content.

Default element: div
Discovery hook: data-sw-toast-viewport
Role: region

Props

Prop Type Default

duration number 5000

Description: Configures the duration option for the Viewport part.
Kind: option
Targets: -
Full type: number

gap string "0.5rem"

Description: Configures the gap option for the Viewport part.
Kind: option
Targets: -
Full type: string

limit number 3

Description: Configures the limit option for the Viewport part.
Kind: option
Targets: -
Full type: number

peek string "1rem"

Description: Configures the peek option for the Viewport part.
Kind: option
Targets: -
Full type: string

Description: Configures the position option for the Viewport part.
Kind: option
Targets: -
Full type: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-viewport - Marks the Viewport part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-position - Reflects the position prop on the Viewport part.

data-limit - Reflects the limit prop on the Viewport part.

data-duration - Reflects the duration prop on the Viewport part.

Template

Template markup used to create Toast items.

Default element: template
Discovery hook: data-sw-toast-template
Role: -

Props

Prop Type Default

Description: Selects the visual variant for the Template part.
Kind: option
Targets: template, root
Full type: "default" | "error" | "info" | "loading" | "success" | "warning"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-template - Marks the Template part so Starwind Runtime can find it.

Root

The main element that owns the Toast Runtime instance.

Default element: div
Discovery hook: data-sw-toast-root
Role: -

Props

Prop Type Default

Description: Selects the visual variant for the Root part.
Kind: option
Targets: template, root
Full type: "default" | "error" | "info" | "loading" | "success" | "warning"

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-root - Marks the Root part so Starwind Runtime can find it.

data-toast-id - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

Metadata

Attribute Value Description

data-variant - Reflects the variant prop on the Root part.

Content

The content container rendered by Toast.

Default element: div
Discovery hook: data-sw-toast-content
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-content - Marks the Content part so Starwind Runtime can find it.

Title

The accessible title for Toast.

Default element: div
Discovery hook: data-sw-toast-title
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-title - Marks the Title part so Starwind Runtime can find it.

Title Text

Text content for the Toast title.

Default element: span
Discovery hook: data-sw-toast-title-text
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-title-text - Marks the Title Text part so Starwind Runtime can find it.

Description

Supporting description text for Toast.

Default element: div
Discovery hook: data-sw-toast-description
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-description - Marks the Description part so Starwind Runtime can find it.

Action

An optional action button shown inside Toast.

Default element: button
Discovery hook: data-sw-toast-action
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-action - Marks the Action part so Starwind Runtime can find it.

Close

A control that closes Toast.

Default element: button
Discovery hook: data-sw-toast-close
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-toast-close - Marks the Close part so Starwind Runtime can find it.

Runtime API

Factory: createToastManager
Import: @starwind-ui/runtime/toast
Root hook: viewport data-sw-toast-viewport
Option props: -

Component Relationship

Toast Direct primitive

Changelog

View version history v1.0.1 4 releases

v1.0.1

Fixed toasts skipping their entrance animation or leaving incorrect spacing when updated immediately, including when a promise resolves.
Reduced repeated JavaScript when Astro Toast is used with other Starwind components.

v1.0.0

Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.

v0.1.1

Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.

v0.1.0

Introduced the toast manager, templates, updates, dismissal, pause behavior, and notification lifecycle.

Layer Metadata

Toast Primitive uses createToastManager. Styled components: Toast.

primitive Toast Primitive Toast Primitive uses createToastManager. Styled components: Toast. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters toast Toast Notification System Primitives that manage transient notifications and viewport placement. /docs/primitives/toast/ createToastManager @starwind-ui/runtime/toast /docs/runtime/#create-toast-manager viewport raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Toast data-sw-* contract yourself, then initialize createToastManager. html Use the Astro primitive adapter to render Toast anatomy with the Runtime wiring included. Use the React primitive adapter when Toast state participates in React rendering. tsx Use the Vue components to build Toast. div data-sw-toast-viewport region duration number Configures the duration option for the Viewport part. gap string Configures the gap option for the Viewport part. limit Configures the limit option for the Viewport part. peek Configures the peek option for the Viewport part. position "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" Configures the position option for the Viewport part. runtime Marks the Viewport part so Starwind Runtime can find it. data-position prop Reflects the position prop on the Viewport part. data-limit Reflects the limit prop on the Viewport part. data-duration Reflects the duration prop on the Viewport part. template data-sw-toast-template variant "default" | "error" | "info" | "loading" | "success" | "warning" Selects the visual variant for the Template part. Marks the Template part so Starwind Runtime can find it. root data-sw-toast-root Selects the visual variant for the Root part. Marks the Root part so Starwind Runtime can find it. data-toast-id data-state state Reflects the current state on the Root part. data-variant Reflects the variant prop on the Root part. content data-sw-toast-content Marks the Content part so Starwind Runtime can find it. title data-sw-toast-title Marks the Title part so Starwind Runtime can find it. titleText span data-sw-toast-title-text Marks the Title Text part so Starwind Runtime can find it. description data-sw-toast-description Marks the Description part so Starwind Runtime can find it. action button data-sw-toast-action Marks the Action part so Starwind Runtime can find it. close data-sw-toast-close Marks the Close part so Starwind Runtime can find it. Viewport aria-live aria-atomic aria-relevant aria-label tabIndex Template Root Content Title Title Text Description Action type Close @starwind-ui/astro @starwind-ui/astro/toast Generate static templates and a viewport self-init that installs the toast manager. @starwind-ui/react @starwind-ui/react/toast Generate template components plus a viewport effect that installs and destroys the toast manager. @starwind-ui/vue @starwind-ui/vue/toast @starwind-ui/svelte @starwind-ui/svelte/toast /docs/components/toast/ Direct primitive direct-primitive Styled component Toast

Toast Primitive

Anatomy

API Reference

Viewport

Props

Data Attributes

Runtime hooks

Metadata

Template

Props

Data Attributes

Runtime hooks

Root

Props

Data Attributes

Runtime hooks

State

Metadata

Content

Data Attributes

Runtime hooks

Title

Data Attributes

Runtime hooks

Title Text

Data Attributes

Runtime hooks

Description

Data Attributes

Runtime hooks

Action

Data Attributes

Runtime hooks

Close

Data Attributes

Runtime hooks

Runtime API

Related Styled Components

Changelog

v1.0.1

v1.0.0

v0.1.1

v0.1.0