Chakra Docs


⦾ Modals, also known as modal dialogs or modal windows, are a type of graphical user interface (GUI) element that force user interaction before they can return to the system. They are a way to prompt the user for a response or to deliver important information. For example, modals can be used to show error or success messages, to ask the user to confirm an action, or to collect form data.

Modals have a few key characteristics: they are usually centered and overlay the primary content. This overlay, often a semi-transparent "dim" or "fade" of the background content, helps draw attention to the modal. They block interaction with the rest of the application. The user must interact with the modal (e.g., close it, fill out a form, etc.) before they can return to the rest of the application. They are a separate "mode" that requires an explicit user action to enter and exit, hence the term "modal".

Chakra UI's implementation of modals has several features that make it useful:

  • Ease of Use: Chakra provides several built-in components for creating modals, including Modal, ModalOverlay, ModalContent, ModalHeader, ModalFooter, ModalBody, and ModalCloseButton. These components encapsulate common modal patterns, making it easy to create modals without having to build everything from scratch.
  • Flexibility: Chakra's modal components are higBlueBoldy customizable. You can control their appearance and behavior using props, and you can add custom components to the modal body.
  • Accessibility: Chakra's modals are designed with accessibility in mind. For example, when a modal is open, focus is trapped within it, preventing users from accidentally interacting with the rest of the application. This is a key requirement for accessibility, and Chakra handles it automatically.
  • Integration: Chakra's modals are designed to work well with other Chakra components. For example, you can use Chakra's Button component for the modal's close button, or Chakra's Text component for the modal's content.
  • Theming: Chakra's modals support Chakra's theming system. This means you can easily adjust their appearance to match your application's theme.

The following are the various components that comprise Chakra's modal system:

  • Modal: This is the main component that contains all the other modal components. It's responsible for controlling the state of the modal (whether it's open or not) and providing context to its child components.
  • ModalOverlay: This is a semi-transparent layer that covers the page content when the modal is open. It's often used to focus the user's attention on the modal by obscuring the rest of the page.
  • ModalContent: This component houses the actual content of the modal. It can contain any number of other components, such as text, forms, images, and more.
  • ModalHeader: This component is typically used to give a title or a brief description of the modal's purpose. It's placed at the top of the ModalContent.
  • ModalFooter: This is placed at the bottom of the ModalContent and is typically used to house the action buttons for the modal, such as "Save" or "Cancel" buttons. The placement of these actions in a consistent location helps users predict where they will be across different modals.
  • ModalBody: This is where the main content for the modal resides. It's located within the ModalContent, usually between the ModalHeader and the ModalFooter. It can contain text, forms, images, or other components, depending on the purpose of the modal.
  • ModalCloseButton: This is a specialized button designed for closing the modal. It's usually placed at the top-right corner of the ModalContent, allowing users to easily close the modal if they wish to dismiss it.

These components can be imported as follows:


Basic Modal

⦾ In this example, clicking on the "Trigger Modal" button opens the modal dialog. The isOpen state is controlled by the useDisclosure hook from Chakra UI, which conveniently handles the open, close, and toggle actions for components like modals.

When the modal is opened, the focus is trapped within the modal, and it's set to the first tabbable element, enhancing accessibility. Users cannot interact with the content behind the modal until the modal is closed, either by clicking on the "Dismiss" button or the close button at the top.


Focus Control Upon Closure

⦾ In this example, when the modal dialog closes, it does not return the focus to the element that opened the modal ("Launch Modal" button in this case). Instead, the focus shifts to a different content marked by the endRef reference.

We do this by passing endRef to the finalFocusRef prop of the Modalcomponent. The finalFocusRef is a useful feature of Chakra UI's Modal that allows developers to control which element should receive focus when the modal closes. This is particularly useful for accessibility reasons, guiding the user's focus to a relevant place after they have completed their interaction with the modal.

In this particular example, the different content is a Box component that receives the focus after the modal closes. We indicate this using aria-label attribute on the Box. As with all Chakra UI components, you can customize and extend these as needed. For example, we've changed the color scheme of the close button to purple and added an additional button in the footer for another action.

A different element that will capture focus after modal closes.


Establish Initial Focus

⦾ This example demonstrates a powerful aspect of Chakra UI's modal dialog: the ability to control which element within the modal receives focus initially when the modal opens and which element receives focus after the modal closes.

In this example, the initialFocusRef prop is passed to the Modalcomponent and is set to startRef. This means that when the modal opens, the initial focus is set on the first Input field (for "First Name").

The finalFocusRef prop is set to endRef, so after the modal closes, the focus will move to the second button "Focus will move here when modal closes". This is important for accessibility and user experience, especially when there are multiple interactive elements on the page.

The following example also shows how to use Chakra UI's FormControl, FormLabel, and Input components to create a form within a modal dialog. The form takes user input for a first and last name, making this a practical example for a user registration or profile creation scenario. As with all Chakra UI components, you can customize and extend these as needed. For example, we've changed the color scheme of the submit button to green and updated the dismiss button text.

Focus will move here when modal closes


Configuring Transitions

⦾ By default, Chakra UI provides a scaling transition for its modal component. However, you have the ability to change this transition to better suit your needs. This can be achieved by passing themotionPreset prop to your Modal component. This prop can take one of the following values: slideInBottom, slideInRight, scale, or none to disable any transition.

In this example, the JokesModal function component displays a button. Clicking this button opens a modal containing a set of one-liner jokes. The modal utilizes the slideInBottom transition, providing a sliding animation from the bottom of the screen.


Modal Sizing

⦾ When it is necessary to modify the size of the modal, you can pass the size property. This property can take the following values: 'xs', 'sm', 'md', 'lg', 'xl', or 'full', each representing a different modal size.


Customizing the Backdrop

⦾ By default, the backdrop's background color is set toblackAlpha.600. However, if you desire to achieve a different look, you can manipulate the appearance by utilizing backdrop style properties such as backdropBlur, backdropBrightness, backdropContrast, Mono,backdropInvert, and backdropSaturate. These properties allow you to modify different aspects of the backdrop style. To activate these properties, you need to set thebackdropFilter property to 'auto'.

Please take note that the backdrop-filter CSS property might not be supported across all browsers. Hence, in the following example, certain features might not be fully functional on some browsers.

Also, since the Modal is rendered within a Portal, the filter property will not impact the background. This implies that you can only use this property to style components within the Modal.


Additional Functionality:

  • Block Scrolling Upon Opening: When a modal is active, it's typically a best practice to disable scrolling on the main document to keep the user's focus on the content within the modal. Chakra UI respects this accessibility guideline and has this feature enabled by default. However, there might be specific scenarios where you'd want to allow users to scroll the main document while the modal is open. In such cases, Chakra UI provides the blockScrollOnMount prop, which you can set to false to allow scrolling on the main document.
  • Overlay Click Closes Modal: by default, clicking outside the modal content of a Chakra UI modal will close it. This can be a useful feature for users who want to quickly exit the modal without having to specifically click a close button. However, you might want to prevent this behavior in certain cases, such as when the modal contains a form that users might accidentally click out of. Chakra UI provides the closeOnOverlayClick prop for this purpose. By setting it to false, the modal will remain open when users click the overlay, requiring them to explicitly click the close button or use the ESC key to close the modal.
  • Vertically Centered Modal: In its default state, a Chakra UI modal is positioned with a vertical offset of 3.75rem from the top. However, for aesthetic or visibility reasons, you might want the modal to be vertically centered on the page. Chakra UI provides an easy way to do this with the isCentered prop. When you pass the isCentered prop to the Modal component, the modal will be vertically centered on the screen, regardless of the viewport height. If you wish to adjust the default offset, you can pass a custom value to the top prop in the ModalContent.
  • Scroll Behavior: Modal overflow behavior refers to the way scrolling is handled when the content within a modal exceeds the visible area of the screen (viewport). To control the scrolling behavior in such situations, the scrollBehavior property can be utilized. When scrollBehavior is set to inside, scrolling is limited to the ModalBody. This means that if the content within the modal exceeds the available space, a scrollbar will appear within the modal body itself, allowing users to scroll through the content without affecting the rest of the page. This is useful when you want to keep the modal's overall position fixed and maintain a consistent layout. On the other hand, when scrollBehavior is set to outside, the entire ModalContent, including the modal header, body, and footer, will scroll within the viewport. In this case, if the modal content overflows, a scrollbar will appear at the edge of the viewport, allowing users to scroll through the content. This approach is suitable when you want the entire modal to be scrollable, giving users the ability to view all the content within the modal without any restrictions.
  • Rendering Elements as Inactive: When the modal is active or open, it's displayed within a unique portal, and all its sibling elements have the aria-hidden attribute assigned as true. This means that the only visible element to screen readers is the modal. If you wish to alter this behavior, you can deactivate it by setting the useInert property to false.
  • Disabling Focus Locking: By default, modal, alert dialog, and drawer components are designed to lock the focus within them, as a standard accessibility feature. This is generally encouraged to meet accessibility standards, ensuring user interaction is concentrated within these components. However, despite its impact on accessibility, there could be certain scenarios where focus trapping within the modal might not be ideal or necessary. If you want to disable this focus trapping feature, you can do so by setting the trapFocus property and assigning its value to false. This change will prevent the modal from locking user focus within itself.

Did you know?

Creative Idea No. 1

Nested Modals: Chakra UI also supports the use of nested modals. If you find a need to launch a new modal from within an existing modal, you can do this by simply adding a new modal within your existing modal. Here is an example of how to implement a nested modal. Be cautious about using nested modals, as they can be confusing for users and are generally discouraged in UI/UX design.


Creative Idea No. 2

Custom Close Button: While the default close button that comes with Chakra UI's modal is functional and accessible, you might want to create a custom close button that fits better with your app's design. Here's an example of how you can replace the default close button with a custom one.


Creative Idea No. 3

Here's a fun and ingenious use of the Modal component in Chakra UI: creating a "Magic 8 Ball" game. The "Magic 8 Ball" is a popular toy that provides random answers to yes-or-no questions. With Chakra UI's Modal component, we can create a visually appealing and interactive version of the Magic 8 Ball.


copyright © 2023 IHeartComponents |


Special thanks to Stefan Bohacek / Generative Placeholders.