Modal

Focused dialog overlay using the native <dialog> element. Built-in keyboard trap, backdrop, and Escape key handling — no JavaScript framework needed.

Basic Modal

<!-- Trigger -->
<button class="primary"
  data-dialog-open="my-modal">
  Open Modal
</button>

<!-- Native dialog -->
<dialog id="my-modal" aria-labelledby="modal-title">
  <header>
    <h2 id="modal-title">Modal Title</h2>
    <button aria-label="Close"
            data-dialog-close="my-modal">
      <span class="axicon render" data-name="X"></span>
    </button>
  </header>
  <p>Modal body content here.</p>
  <footer>
    <button class="secondary"
            data-dialog-close="my-modal">Cancel</button>
    <button class="primary">Confirm</button>
  </footer>
</dialog>

Variants

Confirmation

Destructive action confirmation. Use button.danger for the primary action.

Information

Read-only content like terms, help text, or previews.

Keyboard Shortcuts

Key	Action
`Escape`	Close modal
`Tab`	Move focus forward
`Shift+Tab`	Move focus back

Semantic Structure

Element	Role	Notes
`dialog`	Container	Native modal — `showModal()` activates it with backdrop
`header`	Title row	Contains `h2` + close button
`p`	Body	Main message or content
`footer`	Actions	Cancel/confirm buttons — cancel always first
`aria-labelledby`	Label	Points to the `h2` id — required

Why Native `<dialog>`?

Focus is trapped inside — keyboard users cannot escape accidentally
Escape closes the modal automatically — no JS needed
::backdrop provides the overlay — no extra HTML element
Screen readers announce it as a dialog with the heading as label
Focus returns to the trigger element when closed

Accessibility

Always include aria-labelledby on <dialog> pointing to the h2
Close button needs aria-label="Close" — the icon alone is not accessible
Cancel action should always appear before destructive actions
Avoid auto-opening modals — they must be triggered by user action

Features

Semantic Structure - Built with native HTML5 elements for maximum reliability.
Theme Aware - Automatically adapts to all 22 Axiom01 themes via OKLCH tokens.
Fully Responsive - Scales perfectly from mobile to desktop screens.
No JS Dependency - Core functionality relies on pure CSS for maximum performance.
Customizable - Easily extendable via Axiom01's design tokens and modifiers.

Use Cases

The Modal component is designed for versatile implementation across modern web applications. Ideal scenarios include:

Dashboards & Admin Panels - Structured data presentation and interface control.
Content Management Systems - Organizing complex information hierarchies and media.
E-Commerce Platforms - Enhancing product discovery and user workflows.
Marketing Sites - Highlighting key product offerings cleanly and effectively.
SaaS Applications - Delivering native-feeling, responsive app experiences.