Modal

Modals focus the user's attention exclusively on one task or piece of information via a window that sits on top of the page content.

View sourceView on npmReport an issue

Modals are a variant of Alert used to present critical information or request user input needed to complete a user's workflow. Modals interrupt a user's workflow by design. When active, a user is blocked from the on-page content and cannot return to their previous workflow until the modal task is completed or the user dismisses the modal. While effective when used correctly, modals should be used sparingly to limit disruption to the user. Modals are commonly used for short and non-frequent tasks, such as editing or management tasks. If a user needs to repeatable perform a task, consider making the task do-able from the main page.

Anatomy

Structure

<Modal>
    <Image /> /* (Optional) Decorative image in the modal */
    <Heading /> /** (Required) The title of the modal */
    <Header /> /** (Optional) Section to the right of the Heading  */
    <Content /> /** (Required) the content of the modal */
    <Footer /> /** (Optional) Section under the content, to the left of the buttons
    <ButtonGroup /> /** (Optional) If there is multiple buttons */
    <Button /> /** (Optional) If there is only 1 button */
</Modal>

Composed Components

A Modal uses the following components:

Button

A button allows a user to initiate an action.

ButtonGroup

A button group handles the spacing and orientation for a grouping of buttons.

Content

A placeholder for the main content section of a component.

Footer

A placeholder for a footer section.

Header

A placeholder for an header section.

Heading

A heading is a primitive component matching Hopper's typography type scale.

Image

An image component that can be used to display images.

Usage

Default

A modal must have an heading and a content.

Image

A modal can have a side banner image. Make sure the image has no essential information as it could be cropped in mobile view. Images should not prevent a user from seeing the close button, be conscious of this.

Choice

A modal can offer a choice between 2 options. Keep the copy not too long in order to help the user quickly make his choice.

Header

Use an header to provide additional information usually in the form of a link or a tooltip that provides more context to the task at hand. Links should open in a new window.

Footer

Use a footer to provide trivial information about content present in the modal, like a step : 1/3.

Buttons

A modal can have a single button. Use a primary button to provide the main action.

Or a group of button. A maximum of 3 buttons are allowed in a modal, when necessary. The secondary and tertiary actions should be using a secondary variant.

Dismissable

By default, a modal will dismiss on outside interactions and esc keydown. However, in some cases, you might want to force the user to explicitly dismiss the modal with a targeted call to action. This is what the isDismissable and the isKeyboardDismissDisabled prop is for.

You can set the isDismissable prop to false and isKeyboardDismissDisabled to true and render a call to action which will manually dismiss the popover by calling a close function.

Controlled

The open state can be handled in controlled mode.

Custom trigger

You don't have to use a ModalTrigger component if it doesn't fit your needs. A modal component can be used on it's own with any custom trigger.

Sizes

A modal can be small, medium, large, extra-large, fullscreen or fullscreenTakeover. The default size is medium.

Choose a size that works best for the amount of modal content you have. Modals with short messages should use a small or medium modal to avoid long single lines; for complex components, like a data table the large or extra large modal will be more accommodating.

Responsive sizes

A modal can have different size in mobile and desktop view.

Custom

A CustomModal is a Modal with a custom layout. A CustomModal must contain a <Heading slot="title"> or have an aria-label or aria-labelledby attribute for accessibility.

Best Practices

be thought of as temporary and not be used for information or actions that need to live on in the interface in a persistent way. Don't use modals to display complex forms or large amounts of information. Modals should:

  • Require that users take an action.
  • Close when users press the Dismiss button, the Cancel button, the ESC key, or when users click the area outside the modal.
  • Not have more than two buttons (primary and secondary) in the footer. This prevents unclear action hierarchy and crowding on mobile screens. Since modals are for focused tasks, they should have focused actions.

Do's and Don'ts

Do
Include a Content section in every modal implementation
Don't
Create a modal without the required Content section
Do
Make the Content component a direct child of the Modal
Don't
Place the Content component inside additional wrapper elements

Props

Modal

isDismissible?

Whether the Modal is dismissable. @deprecated Use isDismissable instead. This prop will be removed in a future version (September 30th, 2025).

Defaults to true.
isDismissable?

Whether the Modal is dismissable.

Defaults to true.
isKeyboardDismissDisabled?

Whether pressing the escape key to close the dialog should be disabled.

size?

The size of the modal.

Defaults to md.
overlayProps?

The props of the overlay

style?

The inline style for the element.

children?

Children of the dialog. A function may be provided to access a function to close the dialog.

className?

The CSS className for the element.

isOpen?

Whether the overlay is open by default (controlled).

defaultOpen?

Whether the overlay is open by default (uncontrolled).

ModalTrigger

isOpen?

Whether the overlay is open by default (controlled).

defaultOpen?

Whether the overlay is open by default (uncontrolled).

CustomModal

isDismissible?

Whether the Modal is dismissable. @deprecated Use isDismissable instead. This prop will be removed in a future version (September 30th, 2025).

Defaults to true.
isDismissable?

Whether the CustomModal is dismissable.

Defaults to true.
isKeyboardDismissDisabled?

Whether pressing the escape key to close the dialog should be disabled.

size?

The size of the CustomModal.

Defaults to md.
overlayProps?

The props of the overlay

style?

The inline style for the element.

children?

Children of the dialog. A function may be provided to access a function to close the dialog.

className?

The CSS className for the element.

isOpen?

Whether the overlay is open by default (controlled).

defaultOpen?

Whether the overlay is open by default (uncontrolled).

Migration Notes

Coming from Orbiter, you should be aware of the following changes:

  • dismissable has been renamed isDismissable.
  • onClose has been removed, use onOpenChange on the ModalTrigger instead.
  • wrapperProps has been renamed overlayProps.