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.
Properties
| 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 |
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) => void | returnValue: An optional value to indicate why the modal was closed. | 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 |
|---|---|---|
close | NordEvent | Dispatched when a modal is closed for any reason. |
cancel | NordEvent | Dispatched before the modal has closed when a user attempts to dismiss a modal. Call `preventDefault()` on the event to prevent the modal closing. |
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:
- <nord-footer>
Footer
The footer is a block of designated space for providing additional information or actions that are positioned below the main content.
- <nord-icon>
Icon
Icons are used to provide additional meaning or in places where text label doesn’t fit. Icon component allows you to display an icon from the Nordicons library.
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:
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):
Avoid unnecessary words and articles in modal titles, such as “the”, “an” or “a”:
Avoid ending in punctuation:
Focus behaviour
- Use the
autofocusattribute to set the initial focus to the first location that accepts user input. - If it is a transactional modal without form inputs, then
autofocusshould 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
autofocusin 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.
Integration
For integration guidelines, please see Web Components documentation .