Modal

Modals are containers appearing in front of the main content to provide critical information or an actionable piece of content.
Works with any type of content
Automatically traps focus when opened
Can be controlled and uncontrolled
Supports Title and Subtitle compound components for accessibility
Closes on Esc key press
Supports custom sizes
Supports custom padding values
Supports multiple positions
Similar components:
Backdrop


Usage

Modal is a controlled component which means that it has an active property and multiple handlers that you can use to change the value of this property. Once Modal is active – it will prevent scrolling of the whole page and will just support scrolling for the content displayed inside the backdrop.

Note: It's safe to keep Modal in your render all the time. Modal will be rendered in the DOM only if it is active. Rendering Modal optionally will prevent its animation from working.

Positioning

Besides the default center position, Modal can be used with bottom, start and end position to be displayed as a drawer. That will change its animation to slide-in and out from either side.

Sizes

Modal comes with a default size that can be customized with size property. You can pass any px or percent value as a string. For bottom Modal, size will change its height instead of the width.

Modal comes with a default padding that can be customized using a unit token value. For example, you can set the padding to x2 with padding={2} or completely remove it by setting padding property to 0.

It also supports responsive property syntax, in case you want to change it based on the viewport size. For example, { s: 4, l: 6 } will reduce the padding on small and medium screens to x4.

To make it easier controlling the state, we're providing a useToggle hook that you can use together with Modal or other components that toggle states.

Composition

Modal supports Modal.Title and Modal.Subtitle compound components that take care of the aria attributes and provide default text styles. You can use them together with a Dismissible utility to implement more complex modal layouts.

Accessibility

  • Modal traps focus inside its root element, which means that using any type of keyboard navigation will keep the focus inside the Backdrop while it's opened.
  • Modal triggers its onClose handler on Esc key press.
  • Using Modal.Title and Modal.Subtitle will automatically apply aria-labelledby and aria-describedby attributes to the dialog element.

Properties

Modal properties:

NameTypeDefaultRequiredComment
activeboolean-false
positioncenter, bottom, start, endcenterfalse
sizestring-falseCustom modal size
paddingnumber-falseCustom modal padding
onOpen() => {}-falseOverlay open handler
onClose() => {}-falseOverlay close handler
childrenReactNode, ({ active }) => ReactNode-false
classNamestring-falseclassName for the root element
attributesobject-falseAttributes for the root element

Modal.Title properties:

NameTypeDefaultRequiredComment
childrenReactNode-false

Modal.Subtitle properties:

NameTypeDefaultRequiredComment
childrenReactNode-false
Previous