# Toast Primitive

Toast is a Starwind Runtime primitive in the notification-system contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Toast anatomy with the Runtime wiring included.
```astro
---
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>
```

### React
Use the React primitive adapter when Toast state participates in React rendering.
```tsx
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>
  );
}
```

### HTML
Render the Toast data-sw-* contract yourself, then initialize createToastManager.
```html
<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>
```

### Vue
Use the Vue 3.5 beta adapter to render Toast anatomy.
```vue
<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>
```
## API Reference
### Viewport
The visible viewport for Toast content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-viewport` |
| Role | `region` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| duration | `number` | 5000 | option | Configures the duration option for the Viewport part. | - |
| gap | `string` | "0.5rem" | option | Configures the gap option for the Viewport part. | - |
| limit | `number` | 3 | option | Configures the limit option for the Viewport part. | - |
| peek | `string` | "1rem" | option | Configures the peek option for the Viewport part. | - |
| position | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | "bottom-right" | option | Configures the position option for the Viewport part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
| `data-position` | prop | - | Reflects the position prop on the Viewport part. |
| `data-limit` | prop | - | Reflects the limit prop on the Viewport part. |
| `data-duration` | prop | - | Reflects the duration prop on the Viewport part. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `data-position`, `data-limit`, `data-duration`, `aria-live`, `aria-atomic`, `aria-relevant`, `aria-label`, `tabIndex` | The live region and manager configuration must be present before hydration. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Template
Template markup used to create Toast items.
| Fact | Value |
| --- | --- |
| Default element | `template` |
| Discovery hook | `data-sw-toast-template` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| variant | `"default" \| "error" \| "info" \| "loading" \| "success" \| "warning"` | "default" | option | Selects the visual variant for the Template part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-template` | runtime | - | Marks the Template part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| template | Yes |

### Root
The main element that owns the Toast Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-root` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| variant | `"default" \| "error" \| "info" \| "loading" \| "success" \| "warning"` | "default" | option | Selects the visual variant for the Root part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-root` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-toast-id` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-variant` | prop | - | Reflects the variant prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-state`, `data-variant` | Toast templates are cloned by the runtime and need the starting visual state. |

### Content
The content container rendered by Toast.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-content` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-content` | runtime | - | Marks the Content part so Starwind Runtime can find it. |

### Title
The accessible title for Toast.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-title` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-title` | runtime | - | Marks the Title part so Starwind Runtime can find it. |

### Title Text
Text content for the Toast title.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-toast-title-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-title-text` | runtime | - | Marks the Title Text part so Starwind Runtime can find it. |

### Description
Supporting description text for Toast.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-toast-description` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-description` | runtime | - | Marks the Description part so Starwind Runtime can find it. |

### Action
An optional action button shown inside Toast.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-toast-action` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-action` | runtime | - | Marks the Action part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| action | Yes |

### Close
A control that closes Toast.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-toast-close` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-toast-close` | runtime | - | Marks the Close part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| close | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `type`, `aria-label` | Generated close controls need an accessible label in the cloned template. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createToastManager`](/docs/runtime/#create-toast-manager) |
| Import | `@starwind-ui/runtime/toast` |
| Root part | viewport |
| Option props | - |
| Option lifecycles | - |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Toast](/docs/components/toast/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/toast` | `createToastManager` |
| Astro Primitive | `@starwind-ui/astro/toast` | `Toast`, `ToastViewport`, `ToastTemplate`, `ToastRoot`, `ToastContent`, `ToastTitle`, `ToastTitleText`, `ToastDescription`, `ToastAction`, `ToastClose` |
| React Primitive | `@starwind-ui/react/toast` | `Toast`, `ToastViewport`, `ToastTemplate`, `ToastRoot`, `ToastContent`, `ToastTitle`, `ToastTitleText`, `ToastDescription`, `ToastAction`, `ToastClose` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Toast` |
| runtime-factory | `createToastManager` |
| part | `Toast.Viewport` |
| part | `Toast.Template` |
| part | `Toast.Root` |
| part | `Toast.Content` |
| part | `Toast.Title` |
| part | `Toast.TitleText` |
| part | `Toast.Description` |
| part | `Toast.Action` |
| part | `Toast.Close` |
## Changelog
### 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.