@spectrum-web-components/tray

Overview

<sp-tray> elements are typically used to portray information on mobile device or smaller screens.

Usage

yarn add @spectrum-web-components/tray

Import the side effectful registration of <sp-tray> via:

import '@spectrum-web-components/tray/sp-tray.js';

When looking to leverage the Tray base class as a type and/or for extension purposes, do so via:

import { Tray } from '@spectrum-web-components/tray';

Anatomy

A tray has a single default slot.

Dialog

<overlay-trigger type="modal">
    <sp-button slot="trigger" variant="secondary">Toggle tray</sp-button>
    <sp-tray slot="click-content">
        <sp-dialog size="s" dismissable>
            <h2 slot="heading">New Messages</h2>
            You have 5 new messages.
        </sp-dialog>
    </sp-tray>
</overlay-trigger>

Menu

<overlay-trigger type="modal">
    <sp-button slot="trigger" variant="secondary">Toggle menu</sp-button>
    <sp-tray slot="click-content">
        <sp-menu style="width: 100%">
            <sp-menu-item selected>Deselect</sp-menu-item>
            <sp-menu-item>Select Inverse</sp-menu-item>
            <sp-menu-item focused>Feather...</sp-menu-item>
            <sp-menu-item>Select and Mask...</sp-menu-item>
            <sp-menu-divider></sp-menu-divider>
            <sp-menu-item>Save Selection</sp-menu-item>
            <sp-menu-item disabled>Make Work Path</sp-menu-item>
        </sp-menu>
    </sp-tray>
</overlay-trigger>

Accessibility

<sp-tray> presents a page blocking experience and should be opened with the Overlay API using the modal interaction to ensure that the content appropriately manages the presence of other content in the tab order of the page and the availability of that content for a screen reader.

Changelog

1.5.0 (2025-04-15)

Bug Fixes

• sp-tabs: ensure tabs become enabled when parent disabled attribute is removed (#5323) (c7efe314c5)
• sp-color-field: color handle positioning within scrollable containers (#5322) (e19e55f6f1)
• sp-menu: fixes larger margin in menu-item (#5350) (86bcd12200)
• sp-menu: menuitem now correctly focus and applies hover styles (#5270) (a69accb8b4)
• sp-menu: captures touchend events on mobile (#5313) (4c2f908a92)
• overlay: prevent overlay close on document scroll (#5308) (8f8735c9ec)
• sp-number-field: prevent keyboard on mobile devices by setting inpu… (#5284) (5a3bc6d24e)