Modal

Modals communicate information using an overlaid window that allows users to remain within the context of their workflow, but demands their attention.

For more information on how to use the features and props for this component, check out the developer documentation.

The use of Modals within your application will require the content of the application to be wrapped with a <ModalManager> component. This will provide a ModalManagerContext from which you can use access the create function. This function is needed in order to create a new Modal. Any options or custom props that the Modal will require must be passed to the Modal via the create function with the following syntax:

create(MyModalComponent, ModalProps, ModalOptions);

Modals offer several props to assist in the rendering of the Modal and its content. These include center, which will render the Modal in the center of the viewport both vertically and horizontally, as well as stretch, which will enlarge the Modal to fill most of the viewport. Modals also offer props for heading, count, actions, and progress that insert additional content. The autoWidth prop will resize the Modal to fit-content rather than maintaining its default fixed width.

Modals are dismissable by default, which means they can be closed by clicking the X Button or by clicking away anywhere within the Backdrop that the Modal renders over. These features are disabled if the dismissable Modal option is set to false. There are several other Modal options (separate from Modal props) that will be covered in this documentation.

Both Modal props and Modal options include a wide range of callback functions that assist in micro-managing the various events that can occur with Modals. Explore the available functions in the props table below.

There are a variety of Modal methods that are available for use within any particular Modal via the ModalContext that is returned from ModalManagerContext. These same functions can be accessed from the parent component responsible for creating the Modal. The methods can be stored on a ref from the return value of the create function.

In the following demo, a Modal will be updated via the update Modal method using both of the approaches detailed above. This allows for the Modal props to be updated from both the component that created the Modal, as well as the Modal itself.

Alert

If a Modal is created with the alert option, it will not be dismissable. An alert Modal will render on top of any other active Modal and is best used for confirmations or error dialogs.

Minimizable, maximizable, and dockable

Modals that are created with the minimizable option will include an action near the close Button that can minimize the Modal. When a Modal is minimized, only its heading is visible in bottom-left of the viewport, with actions to dismiss the Modal or re-open it. It will also close the Backdrop, allowing the user to re-engage with other content. Multiple Modals may be minimized simultaneously.

Modals that are created with the maximizable option will include an action near the close Button that can stretch the Modal to full screen. When a Modal is maximized, it will fill most of the viewport, with actions to dismiss the Modal or collapse it back to its original size.

Modals that are created with the dockable option will render in the bottom-left of the viewport without any Backdrop. The full content of the Modal is visible when docked. Multiple Modals may be docked at once, though only the most recent will be open. Previously docked Modals are minimized once a new Modal is opened.

The following demo will combine all three of these Modal options.