# useToast

## Usage

Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Toasts live in a module-level store, so the hook works in any component; render `ToastViewport` once to give them a place to appear. `LayerProvider` only supplies the viewport's placement and visible limit.

```ts
import { useToast } from '@astryx-vue/core/Toast'
```

```vue
<script setup lang="ts">
import { ToastViewport, useToast } from '@astryx-vue/core/Toast'

const toast = useToast()
</script>

<template>
  <button type="button" @click="toast({ body: 'Document saved successfully', type: 'success' })">
    Show toast
  </button>
  <ToastViewport />
</template>
```

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use for transient success/error feedback that does not require user action. |
| Do | Set `uniqueID` to deduplicate toasts from rapid user actions. |
| Do | Render `ToastViewport` once near the app root, so every toast has a place to appear. |
| Don't | Use for critical errors that require acknowledgment; use `AlertDialog` instead. |

## Examples

Common configurations, variations, and states.

### useToast — Show Toast

Imperative toast notifications triggered with useToast and rendered in the toast viewport.

```vue
<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { ToastViewport, useToast } from '@astryx-vue/core/Toast'

const toast = useToast()

function showToast(): void {
  toast({ body: 'Document saved successfully', type: 'success' })
}
</script>

<template>
  <div class="toast-preview__row">
    <Button label="Show toast" variant="secondary" @click="showToast" />
    <ToastViewport />
  </div>
</template>
```

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `show` | `(options: ToastOptions) => () => void` | Show a toast notification. The returned function dismisses that toast. The hook itself is callable, so `toast({ body })` and `toast.show({ body })` are the same. |
| `dismiss` | `(id: string) => void` | Dismiss a toast by id. It hangs off the returned function: `toast.dismiss(id)`. |
| `clear` | `() => void` | Dismiss every visible toast. Called as `toast.clear()`. |

## Toast options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `body` | `string` | — | The message. Required. |
| `type` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Visual type of the toast. |
| `isAutoHide` | `boolean` | `true` | Whether the toast dismisses itself. `error` toasts stay until they are dismissed. |
| `autoHideDuration` | `number` | `5000` | Auto-dismiss duration in milliseconds. |
| `uniqueID` | `string` | — | Identity shared by toasts that should collapse into one. |
| `collisionBehavior` | `'ignore' \| 'overwrite'` | `'overwrite'` | How a `uniqueID` clash is resolved. |
| `endContent` | `Component` | — | Trailing action rendered after the message, such as an undo button. |
| `onDismiss` | `(reason: 'auto' \| 'manual') => void` | — | Runs when the toast card dismisses itself: the timer, the close button, or a swipe. |
| `onHide` | `(reason: 'auto' \| 'manual') => void` | — | Runs when the toast is removed, however it was dismissed. |