Modal Updated

Usage

Modal displays content that temporarily blocks interaction with the rest of the application. Modals are interruptive, so reach for them sparingly — for confirmations, short forms, or focused tasks the user must complete or dismiss before continuing.

A modal is opened by calling showModal() on the element, and closed with close(), by pressing Esc, by clicking the backdrop, or by submitting a <form method="dialog"> inside it.

import "@nordhealth/components/lib/Modal"

Give each modal an accessible name with aria-labelledby pointing at its header, then trigger it from a button:

Composition New since Jul 24, 2026

A modal can be assembled from three structural light-DOM parts plus an optional standalone close part, all placed as direct children of nord-modal. The structural parts assign themselves to the right zones, so the modal's built-in close button, scrolling body and responsive footer keep working. The nord-modal root stays in shadow DOM — it owns the backdrop, focus trapping and dismissal.

import "@nordhealth/components/lib/ModalHeader"
import "@nordhealth/components/lib/ModalBody"
import "@nordhealth/components/lib/ModalFooter"
import "@nordhealth/components/lib/ModalClose"

nord-modal
├── nord-modal-header   title row, beside the built-in close button
├── nord-modal-body     main content; scrolls when the modal is `scrollable`
├── nord-modal-footer   call-to-action buttons; stacked on narrow, row on wide
└── nord-modal-close    standalone close control; place it anywhere

<nord-modal aria-labelledby="title">
  <nord-modal-header>
    <h2 id="title" class="n-typescale-l">Modal title</h2>
  </nord-modal-header>
  <nord-modal-body>…</nord-modal-body>
  <nord-modal-footer>
    <nord-button-group variant="spaced">
      <nord-button>Cancel</nord-button>
      <nord-button variant="primary">Save changes</nord-button>
    </nord-button-group>
  </nord-modal-footer>
</nord-modal>

The parts are additive — the header, feature and footer slots still work for existing markup. Bring your own heading element in nord-modal-header (the part is layout only); for full-bleed media, use the feature slot directly.

Composable close New since Jul 24, 2026

The modal's built-in close button lives in the header zone, so it only appears when you use a header. When you build completely custom content — a two-column layout, a full-bleed panel, anything without a header — use nord-modal-close instead. It is a standalone control you can place anywhere inside nord-modal; clicking it dismisses the modal through the same cancelable flow as the built-in button (the cancel event still fires and can be prevented).

Left empty, it renders the default close icon — position it against the modal frame (which is position: relative) to float it over your content. Wrap your own control and it becomes a transparent close trigger, e.g. a "Cancel" button in a footer:

<nord-modal aria-labelledby="title">
  <!-- floating icon close, no header required -->
  <nord-modal-close
    style="position: absolute; inset-block-start: var(--n-space-s); inset-inline-end: var(--n-space-s)"
  ></nord-modal-close>

  <div class="your-custom-layout">…</div>

  <!-- or turn any control into a close trigger -->
  <nord-modal-close><nord-button>Not now</nord-button></nord-modal-close>
</nord-modal>

Examples

Sizes

The size attribute controls the max-width of the modal: s, m (default), l, and xl. Small modals suit confirmations, while larger sizes give complex forms more room.

Form with method="dialog"

Set a form's method to "dialog" so submitting it closes the modal without any extra JavaScript. The modal's returnValue is set to the value of the submit button that was pressed. Associate a footer button with the form using its form attribute.

Persistent

Add the persistent attribute so the modal cannot be dismissed by clicking the backdrop or pressing Esc. The close button is hidden automatically, so only the action buttons can dismiss it. Use this for flows the user must explicitly resolve.

Preventing close

When the user attempts to dismiss the modal, it fires a cancel event. Call preventDefault() on that event to keep the modal open — useful for guarding unsaved work. Toggle the checkbox below and try to close the modal.

Feature image

Use the feature slot to place a full-bleed illustration or banner at the top of the modal, above the header. This works well for onboarding, announcements, or empty states.

Feature without header or footer

A feature modal can drop its header and footer entirely, letting the illustration and its own content carry the message.

Forms

Place a <form> inside the modal and associate footer buttons with it via the form attribute. Inputs lay out naturally in the modal body.

Complex forms

Larger modals (size="l") give multi-field forms room to breathe, combining selects, inputs, and a textarea. Stacks switch to a single column on narrow screens.

Custom footer

The footer slot accepts any layout. Combine inline helper content with a button group to build footers richer than a simple row of actions.

Destructive actions

For irreversible actions, use a danger button in the footer and a clear, specific heading. Autofocus the destructive button only when it is the safest default.

Managing focus

Add the autofocus attribute to any interactive element inside the modal to focus it automatically when the modal opens, directing the user to the primary input or action.

Multiple modals

Modals can be stacked — opening a second modal from within the first layers it on top, with focus and backdrop managed automatically.

Scroll behavior

When content overflows, the modal body scrolls internally while the header and footer stay fixed. Compare scrolling inside the modal with scrolling the page behind it.

Trigger events

The modal emits events as it opens and closes, and reports how it was dismissed (backdrop, close button, Esc, or an action button). Open the console to inspect the events as you interact.

Scrollable terms

Add the scrollable attribute for long-form content such as terms and conditions, keeping the heading and footer actions in view while the body scrolls.

RTL

Modals follow the document or container direction. Toggle the direction to see the layout mirror.

Accessibility

• Always give the modal an accessible name by pointing aria-labelledby at the id of its header element.
• The modal traps focus while open and restores focus to the triggering element when it closes. Add autofocus to the element that should receive focus on open, such as the primary action button.
• The modal can be dismissed with the Esc key, the close button, or by clicking the backdrop; intercept the cancel event and call preventDefault() when you need to block dismissal.
• Use persistent for flows that must be explicitly resolved — it disables backdrop and Esc dismissal and hides the close button, leaving only your action buttons.