# Tray

An elevated container pinned to the bottom of the screen.

## Import

```tsx
import { Tray } from '@coinbase/cds-web/overlays/tray/Tray'
```

## Examples

:::tip Accessibility tip

**Labels**

Trays require an accessibility label, which we set to `title` by default. However, if you don't want to provide a `title` or there's other text that gives the user better context to the tray, then you can pass an element id to `accessibilityLabelledBy`. Alternatively, you may directly provide a contextual label to `accessibilityLabel`.

:::

### Basic usage with Callback

The recommended way to use a `Tray` is by passing a callback as children, which receives a `handleClose` function:

```tsx live
function BasicTray() {
  const [visible, setVisible] = useState(false);
  const handleOpen = () => setVisible(true);
  const handleClose = () => setVisible(false);

  return (
    <VStack gap={2}>
      <Button onClick={handleOpen}>Open Tray</Button>
      {visible && (
        <Tray title="Example Title" onCloseComplete={handleClose}>
          {({ handleClose }) => (
            <VStack gap={2}>
              <Text>This is the content of the tray.</Text>
              <Button onClick={handleClose}>Close</Button>
            </VStack>
          )}
        </Tray>
      )}
    </VStack>
  );
}
```

### Using Ref to Control the Tray

:::tip Accessibility tip

**Trigger Focus**

A `ref` to the trigger that opens the tray, along with an `onClosedComplete` method to reset focus on the trigger when the tray closes, needs to be wired up for accessibility (see code example below).

:::

You can also control the Tray using a ref, which provides a `close()` method:

```tsx live
function TrayWithRef() {
  const [visible, setVisible] = useState(false);
  const trayRef = useRef<DrawerRefBaseProps>(null);
  const triggerRef = useRef<HTMLButtonElement>(null);

  const handleOpen = () => setVisible(true);
  const handleClose = () => {
    setVisible(false);
    triggerRef.current?.focus();
  };

  return (
    <VStack gap={2}>
      <Button ref={triggerRef} onClick={handleOpen}>
        Open Tray
      </Button>
      {visible && (
        <Tray ref={trayRef} title="Ref Controlled Tray" onCloseComplete={handleClose}>
          <VStack gap={2}>
            <Text>Control this tray using the ref.</Text>
            <Button onClick={() => trayRef.current?.close()}>Close</Button>
          </VStack>
        </Tray>
      )}
    </VStack>
  );
}
```

### Scrollable Content

Trays with long content will automatically be scrollable.

```tsx live
function ScrollableTray() {
  const [visible, setVisible] = useState(false);
  const handleOpen = () => setVisible(true);
  const handleClose = () => setVisible(false);

  return (
    <VStack gap={2}>
      <Button onClick={handleOpen}>Open Scrollable Tray</Button>
      {visible && (
        <Tray title="Scrollable Content" onCloseComplete={handleClose}>
          {({ handleClose }) => (
            <VStack gap={2}>
              <VStack gap={2}>
                <Text>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
                </Text>
                <Text>
                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
                  culpa qui officia deserunt mollit anim id est laborum.
                </Text>
                <Text>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
                </Text>
                <Text>
                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
                  culpa qui officia deserunt mollit anim id est laborum.
                </Text>
                <Text>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
                </Text>
                <Text>
                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
                  culpa qui officia deserunt mollit anim id est laborum.
                </Text>
                <Text>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
                </Text>
                <Text>
                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
                  culpa qui officia deserunt mollit anim id est laborum.
                </Text>
                <Text>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
                </Text>
                <Text>
                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
                  culpa qui officia deserunt mollit anim id est laborum.
                </Text>
                <Text>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
                  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
                  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
                </Text>
                <Text>
                  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
                  fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
                  culpa qui officia deserunt mollit anim id est laborum.
                </Text>
              </VStack>
              <HStack justifyContent="flex-end">
                <Button onClick={handleClose}>Close</Button>
              </HStack>
            </VStack>
          )}
        </Tray>
      )}
    </VStack>
  );
}
```

### Non-Dismissible Tray

Trays can be configured to prevent the user from dismissing the tray by clicking close, clicking outside, or pressing ESC.

```tsx live
function NonDismissibleTray() {
  const [visible, setVisible] = useState(false);
  const handleOpen = () => setVisible(true);
  const handleClose = () => setVisible(false);

  return (
    <VStack gap={2}>
      <Button onClick={handleOpen}>Open Non-Dismissible Tray</Button>
      {visible && (
        <Tray title="Non-Dismissible Tray" preventDismiss onCloseComplete={handleClose}>
          {({ handleClose }) => (
            <VStack gap={2}>
              <Text>
                This tray cannot be dismissed, user must click an explicit action button to close
                it.
              </Text>
              <Button onClick={handleClose}>Close</Button>
            </VStack>
          )}
        </Tray>
      )}
    </VStack>
  );
}
```

### Multiple Overlay Flow

When transitioning between overlays, ensure proper dismounting using `onCloseComplete`:

```tsx live
function TrayToModalFlow() {
  const [isTrayVisible, setIsTrayVisible] = useState(false);
  const [isModalVisible, setIsModalVisible] = useState(false);

  const openTray = () => setIsTrayVisible(true);
  const closeTray = () => setIsTrayVisible(false);
  const openModal = () => setIsModalVisible(true);
  const closeModal = () => setIsModalVisible(false);

  const handleTrayClose = useCallback(() => {
    closeTray();
    openModal();
  }, []);

  return (
    <VStack gap={2}>
      <Button onClick={openTray}>Start Flow</Button>
      {isTrayVisible && (
        <Tray title="First Step" onCloseComplete={handleTrayClose}>
          {({ handleClose }) => (
            <VStack gap={2}>
              <Text>Click below to continue to the modal</Text>
              <Button onClick={handleClose}>Continue to Modal</Button>
            </VStack>
          )}
        </Tray>
      )}
      <Modal visible={isModalVisible} onRequestClose={closeModal}>
        <ModalHeader title="Second Step" />
        <ModalBody>
          <VStack gap={2}>
            <Text>This is the second step in the flow.</Text>
            <Button onClick={closeModal}>Finish</Button>
          </VStack>
        </ModalBody>
      </Modal>
    </VStack>
  );
}
```

Note: The Tray component is an elevated container that is pinned to the bottom of the screen and provides a standardized way to present bottom sheets in your web application. Key points:

- Use `onCloseComplete` for cleanup when the tray is dismissed
- Children can be either a React node or a render function that receives a `handleClose` function
- The `ref` provides `open()` and `close()` methods for controlling the tray
- When transitioning between overlays, ensure proper dismounting using lifecycle methods

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `onCloseComplete` | `() => void` | Yes | `-` | Action that will happen when tray is dismissed |
| `closeAccessibilityHint` | `string` | No | `-` | Sets an accessible hint or description for the close button. On web, maps to aria-describedby and lists the id(s) of the element(s) that describe the element on which the attribute is set. On mobile, a string that helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label. |
| `closeAccessibilityLabel` | `string` | No | `-` | Sets an accessible label for the close button. On web, maps to aria-label and defines a string value that labels an interactive element. On mobile, VoiceOver will read this string when a user selects the associated element. |
| `focusTabIndexElements` | `boolean` | No | `false` | Allow any element with tabIndex attribute to be focusable in FocusTrap, rather than only focusing specific interactive element types like button. This can be useful when having long content in a Modal. |
| `footer` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Optional footer content that will be fixed to the bottom of the tray |
| `id` | `string` | No | `-` | HTML ID for the tray |
| `key` | `Key \| null` | No | `-` | - |
| `onBlur` | `(() => void)` | No | `-` | Callback fired when the overlay is pressed, or swipe to close |
| `onClose` | `(() => void)` | No | `-` | Action that will happen when tray is dismissed |
| `onVisibilityChange` | `((context: hidden \| visible) => void)` | No | `-` | Optional callback that, if provided, will be triggered when the Tray is toggled open/ closed If used for analytics, context (visible \| hidden) can be bundled with the event info to track whether the multiselect was toggled into or out of view |
| `preventDismiss` | `boolean` | No | `-` | Prevents a user from dismissing the tray by pressing the overlay or swiping |
| `ref` | `((instance: TrayRefProps \| null) => void) \| RefObject<TrayRefProps> \| null` | No | `-` | - |
| `restoreFocusOnUnmount` | `boolean` | No | `true` | If true, the focus trap will restore focus to the previously focused element when it unmounts.  WARNING: If you disable this, you need to ensure that focus is restored properly so it doesnt end up on the body |
| `role` | `dialog \| alertdialog` | No | `-` | WAI-ARIA Roles |
| `title` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | No | `-` | Text or ReactNode for optional Tray title |
| `verticalDrawerPercentageOfView` | `string` | No | `-` | Allow user of component to define maximum percentage of screen that can be taken up by the Drawer |
| `zIndex` | `number` | No | `-` | z-index for the tray overlay |