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.

ModalHeader

The header gives the modal context, its usually composed by the ModalTitle and ModalDismiss.

ModalTitle

Modal heading component.

ModalDismiss

Dismisses the modal.

ModalContent

The ModalContent is the main part of the modal.

ModalFooter

The footer usually contains actions.

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:

Styling

Every modal component can receive a className to customize styling.

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.

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.

• What is this?
• Composability
  • Modal
  • ModalHeader
  • ModalTitle
  • ModalDismiss
  • ModalContent
  • ModalFooter
• Abstracting
• Styling