Modal Component

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.

Copy code

import "@nordhealth/components/lib/Modal"

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

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.

API reference

Modal

Modal component is used to display content that temporarily blocks interactions with the main view of an application. Modal should be used sparingly and only when necessary.

<nord-modal></nord-modal>

Props

Property	Attribute	Description	Type	Default
`open`	`open`	Controls whether the modal is open or not.	`boolean`	`false`
`size`	`size`	Controls the max-width of the modal when open.	`'s' \| 'm' \| 'l' \| 'xl'`	`'m'`
`scrollable`	`scrollable`	By default if a modal is too big for the browser window, the entire modal will scroll. This setting changes that behavior so that the body of the modal scrolls instead, with the modal itself remaining fixed.	`boolean`	`false`
`persistent`	`persistent`	When true, the modal will not close when clicking the backdrop or pressing Escape, and the close button will be hidden. Only programmatic close or custom action buttons can dismiss the modal.	`boolean`	`false`

Slots

Slot name	Description
`Default slot`	Default slot
`header`	Slot which holds the header of the modal, positioned next to the close button.
`feature`	Slot for full bleed content like an image.
`footer`	Slot which is typically used to hold call to action buttons, but can also be used to build custom footers.

Methods

Method name	Parameters	Description
`showModal() => void`	N/A	Show the modal, automatically moving focus to the modal or a child element with an `autofocus` attribute.
`close(returnValue?: string, trigger?: Event) => void`	`returnValue`: An optional value to indicate why the modal was closed. `trigger`: An optional event that triggered the close.	Programmatically close the modal.
`focus(options?: FocusOptions) => void`	`options`: An object which controls aspects of the focusing process.	Programmatically focus the modal.

Event	Detail Type	Description
`cancel`	`ModalCancelEvent`	Dispatched before the modal has closed when a user attempts to dismiss a modal. The event includes a trigger property containing the original event that caused the dismiss. Call preventDefault() on the event to prevent the modal closing.
`close`	`ModalCloseEvent`	Dispatched when a modal is closed for any reason. The event includes an optional trigger property containing the original event that caused the close, if the modal was closed by a user action.

CSS Properties

CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.

Property	Description	Default
`--n-modal-padding-inline`	Controls the padding on the sides of the modal, using our spacing tokens.	`var(--n-space-m)`
`--n-modal-padding-block`	Controls the padding above and below the header of the modal, using our spacing tokens.	`var(--n-space-m)`
`--n-modal-max-inline-size`	Controls the width of the modal.	`620px`

Dependencies

This component is internally dependent on the following components:

Design guidelinesFor designers

Usage

This section includes guidelines for designers and developers about the usage of this component in different contexts.

Do

Use for confirmations and conditional changes.
Use when the user is required to take an action.
Use when you need to display content that temporarily blocks interactions with the main view of an application.
Use when you need to ask a confirmation from a user before proceeding.
Use for important warnings, as a way to prevent or correct critical errors.

Don’t

Don’t use for nonessential information that is not related to the current userflow.
Don’t use when the modal requires additional information for decision making that is unavailable in the modal itself.
Don’t open a modal window on top of another modal.

Content guidelines

Modal title should be clear, accurate and predictable. Always lead with a strong verb that encourages action. To provide enough context to user, use the {verb} + {noun} content formula:

Edit patient

Edit the patient called John Doe

Discard changes?

Discard?

Delete patient?

Are you sure you want to delete this patent?

When writing modal titles, always write them in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):

New appointment

New Appointment

Avoid unnecessary words and articles in modal titles, such as “the”, “an” or “a”:

Change theme

Change the theme

Avoid ending in punctuation:

Edit patient

Edit patient.

Focus behaviour

Use the autofocus attribute to set the initial focus to the first location that accepts user input.
If it is a transactional modal without form inputs, then autofocus should be set on the primary button in the modal footer. This is for efficiency since most users will simply dismiss the dialog as soon as they have read the message.
If the modal contains a form, use autofocus in the first form field.
Focus remains trapped inside the modal dialog until it is closed.
For more examples and best practices, please see WAI-ARIA Authoring Practices Modal Dialog Example.

Modal

Usage

Examples

Sizes

Form with method="dialog"

Persistent

Preventing close

Feature image

Feature without header or footer

Forms

Complex forms

Custom footer

Destructive actions

Managing focus

Multiple modals

Scroll behavior

Trigger events

Scrollable terms

RTL

Accessibility

API reference

Modal

Props

Slots

Methods

CSS Properties

Dependencies

Footer

Icon

Usage

Do

Don’t

Content guidelines

Focus behaviour