# Toast Primitive

Toast is a Starwind Runtime primitive in the notification-system contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| 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` |