Side Sheet

A dependency-free modal side sheet using native <dialog>. Inspired by Material side sheets and shadcn Sheet, with existing design system tokens taking precedence. This initial package implements the modal variant.

<button type="button" data-side-sheet-target="edit">Open</button>
<dialog data-side-sheet-id="edit" class="side-sheet" data-side="right" aria-labelledby="edit-title">
  <header class="side-sheet__header">
    <h2 id="edit-title" class="side-sheet__title">Edit</h2>
    <button type="button" data-side-sheet-close>Close</button>
  </header>
  <div class="side-sheet__body">Form or supporting content</div>
  <footer class="side-sheet__footer">Actions</footer>
</dialog>

import '@k4k3ru/design-system-side-sheet/auto';
import '@k4k3ru/design-system-side-sheet/style.css';

data-side-sheet-target is reserved for opening controls; its value must match exactly one dialog's data-side-sheet-id. The dialog itself needs no HTML id for JS routing. Keep heading IDs for aria-labelledby accessibility relationships. Empty, missing, duplicated or non-dialog targets are ignored. Values are matched literally, not parsed as CSS selectors. Native disabled and aria-disabled="true" controls are ignored. Use type="button" on triggers inside forms.

The /auto entry installs one delegated document listener and handles markup added later. Nested icons/labels also trigger their closest opening control. For explicitly scoped setup, use bindSideSheets(root) from the main entry; its return value removes the listener. Repeated binding to the same root does not add duplicate listeners.

getSideSheet(dialog) retrieves the shared controller for imperative lifecycle operations such as forced closing on session expiry. Existing new SideSheet(dialog) usage remains supported and reuses the same instance. Pages do not need to create controllers or wire click handlers just to open sheets.

side-sheet:beforeopen is cancelable and provides event.detail.opener; use it to prepare a form or reject opening during a write. side-sheet:open fires after opening.

Use data-side="left" or right (default). Header/footer stay visible while the body scrolls. Below 600px the sheet fills the viewport. Native dialog provides an inert background, modal focus containment and focus restoration. Escape, close controls and backdrop clicks use the same slide/fade exit. Reduced motion skips animation. Background scrolling is locked while open; destroy() restores it and removes listeners. Provide an accessible title, explicit close control and initial focus.

Override --side-sheet-width, --side-sheet-padding, --side-sheet-background, --side-sheet-color, --side-sheet-outline, --side-sheet-radius, --side-sheet-duration, --side-sheet-easing, or --side-sheet-scrim on the element. Motion, color and radius default to existing tokens.

side-sheet:beforeclose is cancelable, with event.detail.reason (escape, backdrop, button, programmatic, destroy). Consumers can prevent dismissal while saving. side-sheet:close fires after dismissal for sensitive-data cleanup. Use close('programmatic', { immediate: true, force: true }) for session expiry; destroy() also forcibly closes. Use this controller instead of calling the native close() when exit animation or dismissal guards are needed.

Build: npm run build. Example: serve the repository and open web/components/side_sheet/example/. No framework or third-party UI package is required.

Smaller size

Use side-sheet--smaller on the component root. Padding: 1.5rem to 1rem; width unchanged.

See shared sizing guidance and examples.