# Tray

A non-modal bar at the bottom of its scroll container or the viewport,
holding a short message and a few actions: unsaved changes
(`Tray.SaveActions`), an undo stack, a bulk selection. Announced politely;
never takes focus; returns focus if it closes with focus inside.

```tsx
import { Tray } from '@tangible/ui';
```

Interactive docs and examples: [Tray in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/components-tray--docs).

## Tray props

| Prop | Type | Default | Description |
| - | - | - | - |
| `open` | `boolean` | | Whether the tray is showing. Controlled only, like Modal: the state it reports (unsaved edits, a selection, an undo stack) is the app's, and the tray never asks to close itself, so there is no `onOpenChange`. |
| `children?` | `ReactNode` | | |
| `placement?` | `"fixed" \| "sticky"` | `'sticky'` | `sticky` pins it to the bottom of its scroll container (the default); `fixed` pins it to the viewport. A fixed tray breaks out of the viewport's frame under a transformed, filtered or contained ancestor, as any `position: fixed` does; the page reserves room at its own bottom for it. |
| `restoreFocusTo?` | `FocusTarget` | | Where focus goes if the tray closes while focus is inside it. Read at close. Defaults to the element focus entered the tray from. |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

### Tray.Message

| Prop | Type | Default | Description |
| - | - | - | - |
| `announcement?` | `string` | | What to announce, when the spoken sentence should differ from the visible message (e.g. visible `Approved "X"` styled in parts, spoken as one sentence). Defaults to the message's text. |
| `children?` | `ReactNode` | | |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

### Tray.Actions

| Prop | Type | Default | Description |
| - | - | - | - |
| `children?` | `ReactNode` | | |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

### Tray.SaveActions

| Prop | Type | Default | Description |
| - | - | - | - |
| `onDiscard` | `() => void` | | Discard the pending changes. The tray never discards on its own (no Escape). |
| `formId?` | `string` | | Id of the form Save submits (`type="submit" form={formId}`). Takes precedence over `onSave`. |
| `labels?` | `TraySaveLabels` | | Button labels, for translation. Defaults are exported as `defaultTraySaveLabels`; a partial object overrides only its keys. |
| `onSave?` | `() => void` | | Save. Alternatively pass `formId` to make Save submit that form; then `onSave` is not called. |
| `saveDescription?` | `string` | | Why Save is unavailable, e.g. "Fix 2 errors to save". Wired to Save via `aria-describedby`. |
| `saveDisabled?` | `boolean` | `false` | Save is unavailable (e.g. the form is invalid). It stays focusable and is announced as dimmed (`aria-disabled`), so a keyboard user can still find it and hear why; activation does nothing. Pair with `saveDescription`. |
| `saving?` | `boolean` | `false` | A save is in flight: Save shows a spinner and ignores activation, but keeps focus. Named for the domain; it drives Button's `loading`. |
| `size?` | `"lg" \| "md" \| "sm"` | `'md'` | Size of both buttons. |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

## Other exports

- `defaultTraySaveLabels`: `Required<Omit<TraySaveLabels, "saving">>`

## Examples

Stories: Basic, Unsaved Changes, Form Submit, Undo, Bulk Selection, Fixed, Save States ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/components-tray--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-tray-gutter`
- `--tui-tray-bg`
- `--tui-tray-fg`
- `--tui-tray-border`
- `--tui-tray-radius`
- `--tui-tray-shadow`
- `--tui-tray-block-size`
- `--tui-tray-offset`
- `--tui-tray-max-width`
- `--tui-tray-padding-inline-start`
- `--tui-tray-padding-inline-end`
- `--tui-tray-gap`
- `--tui-tray-z`
- `--tui-tray-message-fg`
- `--tui-tray-message-weight`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/components-tray--docs
