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.
Interactions / Component reference
Dialog and modal
Native HTML dialog with focus handling and Escape support.
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
Use dialog.xsh-dialog and open it using data-xsh-open="#xsh-modal-id". Use data-xsh-close within the dialog. The script restores focus to the opener.
Live example
Interactive · Real frameworkExample markup
<button class="xsh-btn xsh-btn-primary" data-xsh-open="#xsh-doc-dialog">Open dialog</button>
<dialog class="xsh-dialog" id="xsh-doc-dialog" aria-labelledby="xsh-dialog-title"><div class="xsh-stack"><h2 class="xsh-h2" id="xsh-dialog-title">Review your choice</h2><p class="xsh-muted">Native modal behavior with focus management.</p><div class="xsh-flex xsh-gap-3"><button class="xsh-btn xsh-btn-secondary" data-xsh-close>Cancel</button><button class="xsh-btn xsh-btn-primary" data-xsh-close>Confirm</button></div></div></dialog>Production guidance
Always provide a meaningful accessible name and an obvious close action. Avoid nesting dialogs.
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 →
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-dialog | Core component | CSS + optional behavior |
.xsh-dialog-header | Composable modifier / structure class | CSS + optional behavior |
Implementation details
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.
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.