Interactions / Component reference

Drawer and offcanvas

Side-panel experiences implemented with native dialog under the hood.

V1 BETA / DOCUMENTEDLive variants · API · Accessibility · Responsive guidance

LIVE COMPONENT REFERENCE

Modal and drawer triggers

The native dialog element supplies focus and Escape behavior; the framework styles it and optionally controls opening and closing.

Actual Xshna CSSResize to test wrapping

HTML · COPY AND USE

<div class="xsh-ref-flex"><button type="button" class="xsh-btn xsh-btn-primary" data-xsh-open="#xsh-ref-modal">Open dialog</button><button type="button" class="xsh-btn xsh-btn-outline" data-xsh-open="#xsh-ref-drawer">Open drawer</button></div><dialog class="xsh-dialog" id="xsh-ref-modal" aria-labelledby="xsh-ref-modal-title"><header class="xsh-dialog-header"><h3 id="xsh-ref-modal-title">Confirm changes</h3><button class="xsh-btn xsh-btn-ghost" type="button" data-xsh-close>Close</button></header><p>Use a native modal for an action requiring focused attention.</p><button class="xsh-btn xsh-btn-primary" type="button" data-xsh-close>Done</button></dialog><dialog class="xsh-dialog xsh-drawer" id="xsh-ref-drawer" aria-label="Example drawer"><h3>Details</h3><p>A drawer is useful for supplementary content.</p><button class="xsh-btn xsh-btn-primary" type="button" data-xsh-close>Close drawer</button></dialog>

Overview

Apply xsh-drawer to a dialog with data-xsh-side=start|end. The same data-xsh-open/data-xsh-close API powers the drawer.

Live example

Interactive · Real framework

Example markup

<button class="xsh-btn xsh-btn-primary" data-xsh-open="#xsh-doc-drawer">Open drawer</button>
<dialog class="xsh-drawer" data-xsh-side="end" id="xsh-doc-drawer" aria-labelledby="xsh-drawer-heading"><div class="xsh-drawer-head"><h2 class="xsh-h2" id="xsh-drawer-heading">Workspace settings</h2><button class="xsh-btn xsh-btn-ghost" data-xsh-close aria-label="Close drawer">×</button></div><p class="xsh-muted">Create complex sidebar forms and filters here.</p></dialog>

Production guidance

Native dialog keeps modal interaction focus-contained. Non-modal persistent sidebars use xsh-shell.

Customize this component through --xsh-* CSS tokens, data-xsh-* configuration attributes and documented xsh-* utilities. Use the optional JavaScript distribution only when an interactive behavior is needed.

Build with confidenceOpen interactive design playground →

EXACT NAMES FROM THE SHIPPED STYLESHEETS

Complete selector inventory

These selectors exist in the current distribution. An entry in this table does not imply that arbitrary modifier combinations are meaningful; use the examples above for the intended composition.

Class	Purpose	Delivery
`.xsh-drawer`	Core component	CSS-only
`.xsh-drawer-head`	Composable modifier / structure class	CSS-only

ENGINEERING AND INTEGRATION

Implementation details

Semantic structure

Use showModal() for modal behavior instead of approximating a modal with a positioned div.

Compose existing xsh- classes on the appropriate HTML element. Keep content order meaningful when CSS is disabled.

Interactive behavior

A modal must restore focus to a sensible target when it closes.

Load xshna.min.js only if the documented interaction needs it. Your application remains responsible for data, persistence and business rules.

Responsive and localization

Test Escape, scroll locking, focus trapping and nested overlay conflicts.

Test 320px-wide viewports, container-constrained instances, keyboard zoom, longer translations and right-to-left text where relevant.

Theme and customization

Use --xsh-* CSS variables for theme values and data-xsh-design / data-xsh-density on the xsh-app root.

Prefer design tokens over hard-coded overrides so components remain coherent across personalities.

ACCEPTANCE CHECKLIST

What to verify before shipping

Confirm every documented class used by the feature exists in the release CSS.
Navigate controls using Tab, Shift+Tab, Enter, Space and Escape where appropriate.
Test with reduced motion, high contrast, 200% text zoom and a narrow mobile viewport.
Verify disabled, loading, empty, error and long-content states where relevant.
Check actual application behavior independently of the preview: these examples use illustrative data.