sp-tray

NPM 1.10.0

View Storybook
Overview API Changelog

Overview

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

Usage

See it on NPM! How big is this package in your project?

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.

Auto-detection behavior

By default, <sp-tray> automatically detects whether its slotted content includes keyboard-accessible dismiss buttons (like <sp-button>, <sp-close-button>, or HTML <button> elements). When no dismiss buttons are found, the tray renders visually hidden dismiss buttons before and after its content to support mobile screen readers, particularly VoiceOver on iOS where users navigate through interactive elements sequentially.

These built-in dismiss buttons:

  • Are visually hidden but accessible to screen readers
  • Allow mobile screen reader users to easily dismiss the tray from either the beginning or end of the content
  • Are labeled "Dismiss" for clear screen reader announcements

This dismiss helper pattern is also implemented in the <sp-picker> component, which uses the same approach when rendering menu content in a tray on mobile devices.

Content has no buttons

This example shows the default behavior where the tray automatically detects that the menu content lacks dismiss buttons and renders visually hidden helpers. Screen readers will announce them as "Dismiss, button" and these helpers are keyboard accessible.

<overlay-trigger type="modal">
    <sp-button slot="trigger" variant="secondary">
        Toggle menu content
    </sp-button>
    <sp-tray slot="click-content">
        <sp-menu style="width: 100%">
            <sp-menu-item>Deselect</sp-menu-item>
            <sp-menu-item>Select Inverse</sp-menu-item>
            <sp-menu-item>Feather...</sp-menu-item>
            <sp-menu-item>Select and Mask...</sp-menu-item>
        </sp-menu>
    </sp-tray>
</overlay-trigger>
 Content has buttons

This example shows auto-detection recognizing that the dialog has its own dismiss functionality, so no additional helpers are rendered.

<overlay-trigger type="modal">
    <sp-button slot="trigger" variant="secondary">
        Toggle dialog content
    </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>
 Manual override

Set has-keyboard-dismiss (or has-keyboard-dismiss="true") to prevent the tray from rendering visually hidden dismiss helpers, even when no buttons are detected. You are then responsible for ensuring that your tray content has keyboard-accessible dismiss functionality.

<overlay-trigger type="modal">
    <sp-button slot="trigger" variant="secondary">
        Toggle without helpers
    </sp-button>
    <sp-tray slot="click-content" has-keyboard-dismiss>
        <p>
            Custom content that should have custom dismiss functionality, even
            though the tray didn't detect buttons in this slot.
        </p>
    </sp-tray>
</overlay-trigger>

Attributes and Properties

Property Attribute Type Default Description hasKeyboardDismissButton has-keyboard-dismiss boolean false When set, prevents the tray from rendering visually-hidden dismiss helpers. Use this if your slotted content has custom keyboard-accessible dismiss functionality that the auto-detection doesn't recognize.

By default, the tray automatically detects buttons in slotted content.

open open boolean false

Slots

Name Description default slot content to display within the Tray

Events

Name Type Description close Event Announces that the Tray has been closed.

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/base@1.10.0
    • @spectrum-web-components/modal@1.10.0
    • @spectrum-web-components/underlay@1.10.0
    • @spectrum-web-components/shared@1.10.0
    • @spectrum-web-components/reactive-controllers@1.10.0

1.9.1

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/modal@1.9.1
    • @spectrum-web-components/underlay@1.9.1
    • @spectrum-web-components/base@1.9.1
    • @spectrum-web-components/reactive-controllers@1.9.1
    • @spectrum-web-components/shared@1.9.1

1.9.0

Patch Changes

  • Updated dependencies [7d23140]:
    • @spectrum-web-components/reactive-controllers@1.9.0
    • @spectrum-web-components/modal@1.9.0
    • @spectrum-web-components/underlay@1.9.0
    • @spectrum-web-components/base@1.9.0
    • @spectrum-web-components/shared@1.9.0

1.8.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/modal@1.8.0
    • @spectrum-web-components/underlay@1.8.0
    • @spectrum-web-components/base@1.8.0
    • @spectrum-web-components/reactive-controllers@1.8.0
    • @spectrum-web-components/shared@1.8.0

1.7.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/modal@1.7.0
    • @spectrum-web-components/underlay@1.7.0
    • @spectrum-web-components/base@1.7.0
    • @spectrum-web-components/reactive-controllers@1.7.0
    • @spectrum-web-components/shared@1.7.0

1.6.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/modal@1.6.0
    • @spectrum-web-components/underlay@1.6.0
    • @spectrum-web-components/base@1.6.0
    • @spectrum-web-components/reactive-controllers@1.6.0
    • @spectrum-web-components/shared@1.6.0

1.5.0

Patch Changes

  • #5271 165a904 Thanks @renovate! - Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.

  • Updated dependencies [165a904]:

    • @spectrum-web-components/modal@1.5.0
    • @spectrum-web-components/underlay@1.5.0
    • @spectrum-web-components/base@1.5.0
    • @spectrum-web-components/reactive-controllers@1.5.0
    • @spectrum-web-components/shared@1.5.0

1.4.0

Patch Changes

  • Updated dependencies []:
    • @spectrum-web-components/modal@1.4.0
    • @spectrum-web-components/underlay@1.4.0
    • @spectrum-web-components/base@1.4.0
    • @spectrum-web-components/reactive-controllers@1.4.0
    • @spectrum-web-components/shared@1.4.0

1.3.0

Patch Changes

  • Updated dependencies [ea38ef0]:
    • @spectrum-web-components/reactive-controllers@1.3.0
    • @spectrum-web-components/modal@1.3.0
    • @spectrum-web-components/underlay@1.3.0
    • @spectrum-web-components/base@1.3.0
    • @spectrum-web-components/shared@1.3.0

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.2.0 (2025-02-27)

Note: Version bump only for package @spectrum-web-components/tray

1.1.2 (2025-02-12)

Note: Version bump only for package @spectrum-web-components/tray

1.1.1 (2025-01-29)

Note: Version bump only for package @spectrum-web-components/tray

1.1.0 (2025-01-29)

Bug Fixes

  • lock prerelease versions for Spectrum CSS (#5014) (8aa7734)

1.0.3 (2024-12-09)

Note: Version bump only for package @spectrum-web-components/tray

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/tray

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/tray

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/tray

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/tray

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/tray

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/tray

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/tray

0.47.0 (2024-08-20)

Bug Fixes

  • tray: removed nonNull operator and initialized resolveTransitionPromise with dummy func (#4658) (1a8a479)

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/tray

0.45.0 (2024-07-30)

Bug Fixes

  • tray sp-tray now doesn't automatically retract when opened with fewer items in the iOS simulator ([4572] (https://github.com/adobe/spectrum-web-components/issues/4572)) ([56366ce] (https://github.com/adobe/spectrum-web-components/commit/56366ce2750bb4bb5c6e3fa5fe7d809434497adb))

Note: Version bump only for package @spectrum-web-components/tray

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/tray

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/tray

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/tray

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/tray

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/tray

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/tray

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/tray

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/tray

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/tray

0.41.0 (2024-02-13)

Bug Fixes

  • tray: only allow "click" events when they "pointerdown"ed on the Underlay (#4020) (4f9aa4a)

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/tray

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/tray

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/tray

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/tray

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/tray

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/tray

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/tray

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/tray

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/tray

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/tray

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/tray

0.38.0 (2023-09-05)

Bug Fixes

  • picker: ensure the Menu opens in a Tray on mobile (6be2bed)

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/tray

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/tray

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/tray

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/tray

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/tray

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/tray

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/tray

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/tray

0.30.0 (2023-05-03)

Bug Fixes

  • centralize updated first focusable selector (300e84c)
  • correct the relationship between overlayWillCloseCallback and phased animations (c63db8d)
  • dialog: normalize sizing technique to align with future t-shirt size usage (da33797)
  • leverage "dvh" rather than measured screen height (84b9df0)
  • tray: add tray pattern (0915fa5)
  • tray: include correct dependency listing (51cb231)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)
  • include all Dev Mode files in side effects (f70817c)
  • picker: support responsive delivery of menu (20031d1)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
  • tray: use spectrum tokens (cdd78b2)
  • update lit-* dependencies, wip (377f3c8)

0.5.3 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/tray

0.5.2 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/tray

0.5.1 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/tray

0.5.0 (2023-02-08)

Features

  • tray: use spectrum tokens (cdd78b2)

0.4.9 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/tray

0.4.8 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/tray

0.4.7 (2022-12-08)

Bug Fixes

  • leverage "dvh" rather than measured screen height (84b9df0)

0.4.6 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/tray

0.4.5 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/tray

0.4.4 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/tray

0.4.3 (2022-10-17)

Bug Fixes

  • correct the relationship between overlayWillCloseCallback and phased animations (c63db8d)

0.4.2 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/tray

0.4.1 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/tray

0.4.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.3.12 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/tray

0.3.11 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/tray

0.3.10 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/tray

0.3.9 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/tray

0.3.8 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/tray

0.3.7 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/tray

0.3.6 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/tray

0.3.5 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/tray

0.3.4 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/tray

0.3.3 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/tray

0.3.2 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/tray

0.3.1 (2022-02-03)

Bug Fixes

  • tray: include correct dependency listing (51cb231)

0.3.0 (2022-02-02)

Features

  • picker: support responsive delivery of menu (20031d1)

0.2.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/tray

0.2.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/tray

0.2.1 (2021-12-13)

Note: Version bump only for package @spectrum-web-components/tray

0.2.0 (2021-11-08)

Features

  • update lit-* dependencies, wip (377f3c8)

0.1.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/tray

0.1.0 (2021-11-02)

Bug Fixes

  • centralize updated first focusable selector (300e84c)

Features

  • adopt DNA@7 base Spectrum CSS (e08cafd)

0.0.7 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/tray

0.0.6 (2021-08-24)

Note: Version bump only for package @spectrum-web-components/tray

0.0.5 (2021-08-17)

Bug Fixes

  • dialog: normalize sizing technique to align with future t-shirt size usage (da33797)

0.0.4 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/tray

0.0.3 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/tray

0.0.2 (2021-05-24)

Bug Fixes

  • tray: add tray pattern (0915fa5)