No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

Modal

A modal focus the user’s attention exclusively on one task or piece of information via a dialog that sits on top of the page content.

usage
import { Modal, ModalTrigger, Heading, Header, Content, Footer, ModalTriggerContext, useModalTriggerContext } from "@sharegate/orbit-ui";
sources
Github

Guidelines

When to use

  • To let a user interact with the application without jumping to a new page and interrupting the user's workflow.

Content

  • Provide enough information for the user to be able to take a decision in the spot, or a way to come back to the choice later.
  • Not use complex layouts, modals are not pages. Consider using a page when a modal layout is getting too complex.
  • Not rely on images or illustrations in order to provide essential information to the user.
  • Not ask the user a question right above the button(s).

Accessibility

  • Make sure to autofocus on the first interactive element in the modal, except if it’s a destructive action as it could trigger unwanted behavior.
  • Prioritize dismissible modals whenever possible in order to give control to the user.
  • Use modals sparingly as it disrupt the user's flow.

If your modal has no way to be dismissed and requires the user to make a choice use an Alert.

Usage

Default

A modal must have an heading and a content.

Editable example

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.

Editable example

Or an illustration. Prefer 1:1 ratio for illustrations to prevent them to render a Modal too high on small resolutions, alternatively in mobile use another illustration that has a 1:1 ratio.

Editable example

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.

Editable example

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.

Editable example

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

Editable example

Buttons

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

Editable example

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.

Editable example

A modal isOpen state or close function can be retrieved from useModalTriggerContext.

Editable example

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 dismissable prop is for.

You can set the dismissable prop to false and render a call to action which will manually dismiss the popover by calling a close function retrieved from the useModalTriggerContext hook.

Inlining the call to useModalTriggerContext in ModalTrigger will not work.

Editable example

Controlled

The open state can be handled in controlled mode.

Editable example

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 which follow a few rules:

  • The custom trigger provide a valid <DialogTriggerContext> with a close function.
  • The custom trigger is responsible of show/hide the modal. This is usually done in combination with an overlay component.
Editable example

API

ModalTrigger

usage
import { ModalTrigger } from "@sharegate/orbit-ui";
NameDescriptionDefault
children*
React children.
string | number | false | true | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal
-
defaultOpen
The initial value of open when in auto controlled mode.
falsetrue
-
dismissable
Whether or not the dialog should close on outside interactions.
falsetrue
true
onOpenChange
Called when the open state change.
(event: SyntheticEvent<Element, Event>, isOpen: boolean) => void
eventReact's original event.
isOpenIndicate if the menu is visible.
-
open
Whether or not to show the dialog.
falsetrue
-
zIndex
The z-index of of the dialog.
number
-
usage
import { Modal } from "@sharegate/orbit-ui";
slots
"image", "illustration", "heading", "header", "content", "footer", "button", "button-group"
NameDescriptionDefault
dismissable
Whether or not the dialog should close on outside interactions.
falsetrue
true
onClose
Called when a closing event happenened.
(event: SyntheticEvent<Element, Event>) => void
eventReact's original synthetic event.
-
wrapperProps
Additional props to render on the wrapper element.
Partial<OmitInternalProps<InnerBoxProps, never> & RefAttributes<any>>
-
zIndex
The z-index of the dialog.
number
1

Heading

usage
import { Heading } from "@sharegate/orbit-ui";
NameDescriptionDefault
size
An heading can vary in size.
"xs" | "sm" | "md" | "lg" | "xl" | "2xs" | ResponsiveValue<"xs" | "sm" | "md" | "lg" | "xl" | "2xs">
-
slot
Slot to render into.
string
-

Header

usage
import { Header } from "@sharegate/orbit-ui";
NameDescriptionDefault
children*
React children.
string | number | false | true | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal
-
slot
Slot to render into.
string
-

Content

usage
import { Content } from "@sharegate/orbit-ui";
NameDescriptionDefault
children*
React children.
string | number | false | true | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal
-
slot
Slot to render into.
string
-
usage
import { Footer } from "@sharegate/orbit-ui";
NameDescriptionDefault
children*
React children.
string | number | false | true | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal
-
slot
Slot to render into.
string
-