Sheet

Present an authored native dialog from a viewport edge. Custom element

Markup you author

A modal sheet opens from markup: put command="show-modal" and commandfor on the trigger, naming the explicit id you gave the <dialog>. A non-modal sheet cannot, because the platform has no built-in command for dialog.show(), so leave command off that trigger and the click listener opens it. Close buttons take command="close" on either kind, and the platform copies the button value into returnValue. Timeless reads these attributes and never writes them, so a modal sheet still opens with JavaScript disabled.

Sheet

Copy this markup

<ui-sheet modal>
  <button class="ui-button" data-ui-part="trigger" type="button" command="show-modal" commandfor="settings-sheet">Open sheet</button>
  <dialog id="settings-sheet" aria-labelledby="settings-sheet-title" aria-describedby="settings-sheet-description">
  <div data-ui-part="drag-handle" aria-hidden="true"></div>
    <header>
      <h2 data-ui-part="title" id="settings-sheet-title">Settings</h2>
      <button class="ui-button" data-ui-variant="ghost" data-ui-size="sm" data-ui-part="close" type="button" aria-label="Close sheet" command="close" commandfor="settings-sheet">
        <svg aria-hidden="true" focusable="false" viewBox="0 0 16 16">
      <path d="m4.5 4.5 7 7m0-7-7 7" fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="1"/>
    </svg>
      </button>
      <p data-ui-part="description" id="settings-sheet-description">Configure this preview.</p>
    </header>
    <section>
      <p>Changes apply immediately.</p>
    </section>
    <footer>
      <button class="ui-button" data-ui-variant="secondary" data-ui-part="close" type="button" command="close" commandfor="settings-sheet" value="cancel">Cancel</button>
      <button class="ui-button" data-ui-part="close" type="button" command="close" commandfor="settings-sheet" value="done">Done</button>
    </footer>
  </dialog>
</ui-sheet>

Install

Styles and registration

import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/sheet.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/core/dialog.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/sheet.css'
import '@timelessui/components/css/themes/atmosphere/dialog.css'
import '@timelessui/components/register/ui-sheet'

A register/ import is a side effect: it defines the element as the module evaluates, so it has to run in code the browser loads. To register explicitly instead — to control the timing, or to define into another window — call the function from the matching define/ entry point, which registers nothing on its own:

Explicit registration

import { defineSheetElement } from '@timelessui/components/define/ui-sheet'
defineSheetElement()

Anatomy

Parts are authored in your own markup and identified by the selector below, so your CSS can target the same anatomy without loading Timeless styles. Required parts must be present for the component to work. Private data-ui-internal-* hooks are written by the runtime and must never be authored.

Part	Required	Selector	Purpose
trigger	Yes	[data-ui-part~='trigger']	Native button that opens the sheet. On a modal sheet, add command="show-modal" and commandfor naming the panel id to open it from markup, before any script runs. A non-modal sheet has no declarative equivalent: the platform has no built-in command for dialog.show(), so its trigger stays on the click listener.
panel	Yes	dialog	The native <dialog> element. Give it an explicit id when a trigger or close button invokes it, since an invoker can only name an id the author wrote.
close	No	[data-ui-part~='close']	Optional explicit close button. Add command="close" and commandfor to close it from markup, on modal and non-modal sheets alike; the platform then also copies the button value into returnValue.
drag-handle	No	[data-ui-part~='drag-handle']	Optional grab area for the swipe gesture. A swipe works anywhere on the panel that is not a scrollable region, so this is an affordance rather than a requirement — but it is the one place a drag always starts, which is what a bottom sheet over a scrolling body needs. Decorative: hide it from assistive technology and keep a real close control.
title	No	[data-ui-part~='title'], header > :where(h1, h2, h3)	Names the sheet. Timeless points the panel's aria-labelledby at it, generating an id only if you left one off. A heading in the panel <header> counts without the token. An aria-labelledby you author always wins.
description	No	[data-ui-part~='description'], header > p	Supporting line under the title, wired with aria-describedby the same way. A <p> in the panel <header> counts without the token.

Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes are presence-based: author the attribute with no value, or omit it.

Attribute	Values	Default	Description
modal	presence	absent	Present to open the sheet as a modal, trapping focus and blocking the page behind it. Omit for a non-modal sheet the user can interact around.
open	presence	absent	Present to render the sheet open on load.
position	top · right · bottom · left	right	Which viewport edge the sheet slides in from.

Element API

Attributes above are the authoring surface. These are the DOM properties and events the registered element adds once it upgrades.

<ui-sheet>

Property	Type	Notes
modal	boolean	Reflects the modal attribute, documented above.
open	boolean	Reflects the open attribute, documented above.
position	'top' | 'right' | 'bottom' | 'left'	Reflects the position attribute, documented above.

Event	Detail	Description
ui-open	CustomEvent<SheetEventDetail>	Dispatched after the sheet opens.
ui-close	CustomEvent<SheetEventDetail>	Dispatched after the sheet closes.
ui-dismiss	CustomEvent<SheetEventDetail>	Dispatched when the sheet closes through Escape, a backdrop click, or a swipe past the dismiss threshold, rather than through an explicit control. The detail names which. A swipe reports swipe and behaves exactly like a backdrop click, because that is what it is: a pointer gesture on the overlay rather than a command.

Styling

Root identity: ui-sheet. Required stylesheets: tokens.css, core/sheet.css, core/button.css, core/dialog.css, themes/atmosphere/tokens.css, themes/atmosphere/button.css, themes/atmosphere/sheet.css, themes/atmosphere/dialog.css.

Set these custom properties to restyle the component:

Custom property	Controls
--ui-sheet-drag-offset	How far the panel has been dragged along its own axis, written as a length while a swipe is in progress and cleared on release. The stylesheet turns it into a translate; setting it yourself only moves the panel.

Design tokens this component reads (31)

These are global Atmosphere tokens. Change them once at the theme level rather than per component.

--ui-accent · --ui-bg-accent · --ui-bg-accent-active · --ui-bg-accent-hover · --ui-bg-control · --ui-bg-control-active · --ui-bg-control-hover · --ui-bg-control-muted · --ui-bg-danger · --ui-bg-danger-active · --ui-bg-danger-hover · --ui-bg-surface · --ui-bg-surface-subtle · --ui-duration-fast · --ui-ease-standard · --ui-fg · --ui-fg-muted · --ui-focus · --ui-line · --ui-radius-control · --ui-radius-lg · --ui-radius-pill · --ui-shadow-control-accent · --ui-shadow-control-active · --ui-shadow-control-danger · --ui-shadow-floating · --ui-shadow-outline-control · --ui-space-2 · --ui-space-3 · --ui-space-4 · --ui-space-5

Accessibility

Keep the native elements, roles, and relationships shown in the example. Timeless adds only the state and keyboard coordination the platform does not already provide, and it never supplies your accessible names — those depend on your content.

Follows the Modal Dialog pattern from the ARIA Authoring Practices Guide.

Key	Action
Escape	Close the sheet. Handled by the native <dialog> element.

A modal sheet traps focus through showModal(); without modal the page stays interactive and focus is not trapped. Timeless restores focus to the trigger either way, including after a swipe. Naming comes from the title and description parts. Swipe-to-dismiss is an addition, never the only way out: Escape and a close control both stay, so the sheet is fully operable without a pointer.

Verify in context

Automated checks cover axe WCAG 2.2 A and AA rules on every documented route. Keyboard, zoom, forced-colors, and screen-reader review still belong to your application.

Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

More examples

Open Sheet in StoryLite for variants, controls, and manual testing.