Modal
What is this?
Modal containers allow merchants to view content that demands attention through an overlay window that opens on top of the current page.
Composability
The Modal is composed by many parts: Modal, ModalHeader, ModalTitle, ModalDismimiss, ModalContent, ModalFooter, and ModalButton.
Modal
The main component, responsible for holding the state.
Loading...
ModalHeader
The header gives the modal context, its usually composed by the ModalTitle and ModalDismiss.
Loading...
ModalTitle
Modal heading component.
Loading...
ModalDismiss
Dismisses the modal.
Loading...
ModalContent
The ModalContent is the main part of the modal.
Loading...
ModalFooter
The footer usually contains actions.
Loading...
Abstracting
The main reason the modal is composable is to enable abstractions. You can create specific modals using the small pieces admin-ui provides. In the example, you can see a confirmation modal that uses this approach:
Loading...
Styling
Every modal component can receive a className to customize styling.
Loading...
Modal Props
Same as div JSX element, and:
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| state | ModalState | Return of useModalState | ✅ | null |
ModalHeader Props
Same as header JSX element.
ModalTitle Props
Same as h1 JSX element.
ModalDismiss Props
Same as button JSX element.
ModalContent Props
Same as div JSX element.
ModalFooter Props
Same as footer JSX element.
ModalButton Props
Same as Admin UI Button, and:
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| dismissModal | boolean | If dismisses the modal on click | 🚫 | false |
Components
When to add content in a Page, in a Card or in a Popover instead of in a Modal?
- Add content in the Page itself or in a Card when it's always essential for the main job.
- Add content in a Popover when there isn't a lot of content, when it isn't essential for the main job, when it makes sense to keep the Page content visible for comparison, and the trigger that opens it isn't inside a Menu.
When to use an Alert or a Toast instead of a Modal?
- Choose an Alert to notify the merchant and call attention to an information without interrupting the flow. An Alert must load at the same time as the page, it can't appear afterwards.
- Choose a Toast to give brief feedback on ordinary actions that don't require the merchants' exclusive attention. A Toast can appear at any time, such as for actions occurring in the background.
Variants
When should a Modal be small, medium or large?
In general, the size of the Modal should be chosen so its content can be comfortably consumed. Considering this, follow the recommendations below:
- Use a small Modal to confirm actions. Confirmation messages should always be short enough to comfortably fit in a small modal.
- Use a medium Modal for long texts, such as terms and conditions, since the width has the ideal character count for comfortable reading.
- Use a large Modal only if none of the scenarios above apply and if the content is very related to the main job of the current Page.
What to avoid:
- Avoid using large Modals with columns. The content should be focused in a specific action.
When should a Modal have a vertical scroll?
When the Modal reaches its maximum height, it can have a vertical scroll. Whenever possible, make the content brief and avoid vertical scroll.
What to avoid:
- Don't use vertical scroll in Modals intended at confirming actions.
- Don't leave actions visible only after the user scrolls. Use a Footer to display actions.
When should the Modal include a Footer?
- When the main task of the Modal is to confirm an action or fill in a form, the action should be in a Footer.
- There should always be a Cancel action in the left and an action that submits the information in the right. The Cancel action has the same effect as the Close button in the header.
- When the purpose of a Modal is to select a single item in a list, clicking the item itself should submit the selection. No separate actions should be required.
Position
What should be the position of content in a Modal?
If you want to know how to position components in a Modal, read the Position section in the component's documentation.
What to avoid:
Don't position the main actions of a Modal in its body. Always position them in a Footer, following our recommendations.
Don't position the main actions of a Modal in its body. Always position them in a Footer, following our recommendations.
Behavior
When should a Modal open or close automatically?
Never. A Modal should always be triggered from user action.
When should other overlays (Toast, Popover or Tooltip) appear on top of a Modal?
- If there is a Popover or Tooltip trigger inside the content of a Modal, it can be displayed over the Modal.
- Only critical Toasts should appear on top of a Modal. Success Toasts only appear after the Modal is closed.
Content
What should be the content of a Modal?
Conduct UX research to understand the merchants' needs. Display in a Modal the content related to a minor job within a Page's main job. For example, minor jobs can be filling a small form before performing an action (e.g. to create a new release) or viewing additional information (e.g. technical events of an order).
What should be the Title of a Modal?
- In Modals with actions, the Title should include a verb in the infinitive and an object. For example, Create release. When possible, reuse the label of the action that triggered the Modal.
- In Modals that only display information, the Title should act as a label that describes the content of the view. For example, Terms and conditions.
- Use sentence case, but capitalize proper nouns.
What to avoid:
- Don't use punctuation.
- Don't use more than three words.
- Don't use personal pronouns.