# Snackbar

> Slug: `snackbar` · Category: Feedback

## When to use
- Transient, non-blocking feedback after a user action — "Saved", "Copied to clipboard", "Address removed".
- Brief status updates that don't require acknowledgment.

## When NOT to use
- For persistent inline notices — use `NoticeBar`.
- For confirmations or destructive prompts — use `Modal`.
- For full-page error states — use `FullPageInterruption`.

## Variants & decision tree
A single visual layout with configurable behavior:

- **Plain** — `label` only.
- **With decoration** — `hasDecoration={true}` adds a leading check-circle icon. Use for confirmations of successful actions.
- **Dismissible** — `isDismissable={true}` adds a close button (`onDismiss`).
- **Animated entry/exit** — pair `triggerAnimation` with `animationType` (`'up'` or `'down'`); set `dismissSnackbar` to fade out.

> Snackbar is prop-controlled. Manage visibility (`isVisible`), animations, and auto-dismiss timers externally.

## States
- `isVisible` keeps the bar on screen.
- `triggerAnimation` runs the entry animation.
- `dismissSnackbar` plays the fade-out animation.
- `inverse` swaps to dark-background styling.
- `isSnapshot` positions absolutely for visual testing.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | — | Required text. Empty renders nothing. |
| `id` | `string` | — | Optional container id. |
| `hasDecoration` | `boolean` | `false` | Show leading check icon. |
| `decorationIcon` | `ReactNode` | check-filled | Override the decoration icon. |
| `leadingIconA11yLabel` | `string` | — | `aria-label` for the decoration icon. |
| `isDismissable` | `boolean` | `false` | Show close button. |
| `onDismiss` | `() => void` | — | Close-button click. |
| `isVisible` | `boolean` | `false` | Force visible regardless of animation. |
| `animationType` | `'up' \| 'down'` | — | Slide direction. |
| `triggerAnimation` | `boolean` | `false` | Start entry animation. |
| `dismissSnackbar` | `boolean` | `false` | Play fade-out. |
| `inverse` | `boolean` | inherited | Dark-background styling. |
| `closeIcon` | `ReactNode` | close-outlined | Override close icon. |

## Usage examples
```tsx
const [show, setShow] = useState(false);

<Button onClick={() => setShow(true)}>Save</Button>

<Snackbar
  label="Changes saved"
  hasDecoration
  isDismissable
  isVisible={show}
  triggerAnimation={show}
  animationType="up"
  onDismiss={() => setShow(false)}
/>

// Auto-dismiss after 4s
useEffect(() => {
  if (!show) return;
  const id = setTimeout(() => setShow(false), 4000);
  return () => clearTimeout(id);
}, [show]);
```

## Composition
Render once near the app root or in a portal so it's never clipped by overflow. Pair with a queue if multiple snackbars may fire — Snackbar itself doesn't queue.

## Accessibility
- Keep messages short and actionable; avoid critical info that users might miss.
- For success notifications, set `leadingIconA11yLabel` ("Success") so the decoration is announced.
- The close button uses `aria-label="close message"`.
- For more urgent feedback, prefer `NoticeBar` with an alert variant (announced via `role="alert"`).

## Do / Don't
- Do auto-dismiss after ~3–5 seconds.
- Do offer `isDismissable` so users can close immediately.
- Don't put critical messages here — they may be missed.
- Don't render multiple Snackbars stacked at once.
