Modal

A Modal Dialog is used to represent information that demands attention and/or action from the users, preventing them from interacting with the rest of the page. It follows the WAI-ARIA Dialog (Modal) Pattern.

Behavior

Modal is a compound component with the following composites:

Name	Description
ModalHeader	Modal header. Renders header element
ModalContent	Content of the modal. Renders a section element
ModalFooter	Modal footer. Renders a footer element
ModalButton	Renders a admin-ui/Button

function ModalDialog() {
  const modal = useModalState()

  return (
    <Box>
      <ModalDisclosure state={modal}>
        <Button>Publish</Button>
      </ModalDisclosure>
      <Modal aria-label="Publish modal" state={modal} size="small">
        <ModalHeader title="Publish content" />
        <ModalContent>
          <Text>
            Are you sure you want to publish this content? This action cannot be
            undone.
          </Text>
        </ModalContent>
        <ModalFooter>
          <Button variant="secondary">Cancel</Button>
          <Button>Confirm</Button>
        </ModalFooter>
      </Modal>
    </Box>
  )
}

Examples

Sizes

The modal comes in three different sizes: small, regular, and large.

Small

function SmallModal() {
  const modal = useModalState()

  return (
    <Box>
      <ModalDisclosure state={modal}>
        <Button>Small</Button>
      </ModalDisclosure>
      <Modal aria-label="Small" state={modal} size="small">
        <ModalHeader title="Small" />
        <ModalContent>
          <Text>Small Modal</Text>
        </ModalContent>
        <ModalFooter>
          <Button>Confirm</Button>
        </ModalFooter>
      </Modal>
    </Box>
  )
}

Regular (default)

function RegularModal() {
  const modal = useModalState()

  return (
    <Box>
      <ModalDisclosure state={modal}>
        <Button>Regular</Button>
      </ModalDisclosure>
      <Modal aria-label="Regular" state={modal}>
        <ModalHeader title="Regular" />
        <ModalContent>
          <Text>Regular Modal</Text>
        </ModalContent>
        <ModalFooter>
          <Button>Confirm</Button>
        </ModalFooter>
      </Modal>
    </Box>
  )
}

Large

function LargeModal() {
  const modal = useModalState()

  return (
    <Box>
      <ModalDisclosure state={modal}>
        <Button>Large</Button>
      </ModalDisclosure>
      <Modal aria-label="Large" state={modal} size="large">
        <ModalHeader title="Large" />
        <ModalContent>
          <Text>Large Modal</Text>
        </ModalContent>
        <ModalFooter>
          <Button>Confirm</Button>
        </ModalFooter>
      </Modal>
    </Box>
  )
}

Usage

import {
  Modal,
  ModalHeader,
  ModalContent,
  ModalFooter,
  ModalButton,
  ModalDisclosure,
  useModalState,
} from '@vtex/admin-ui'

Accessibility

• Modal has the dialog role.
• Modal has aria-modal set to true.
• When Modal opens, focus moves to an element inside of it.
• Focus is trapped within the Modal.
• ESC closes `Modal` unless hideOnEsc is set to false.
• Clicking outside the Modal closes it unless hideOnClickOutside is set to false.

Props

Modal

Name	Type	Description	Required	Default
aria-label	string	Modal aria-label	✅	-
state	ModalState	Return of useModalState	✅	-
size	small, regular or large	Modal size	🚫	regular
hideOnClickOutside	boolean	When enabled, user can hide the dialog by clicking outside it	🚫	true
hideOnEsc	boolean	When enabled, user can hide the dialog by pressing ESC	🚫	true

useModalState

Name	Type	Description	Required	Default
visible	boolean	If is initially visible	🚫	false

ModalHeader

All props of header JSX element, and:

Name	Type	Description	Required	Default
title	ReactNode	Title of the modal	🚫	null
containerCsx	SxStyleProp	Styles of the buttons container	🚫	{}

ModalButton

Props

All props of Button, and:

Name	Type	Description	Required	Default
closeModalOnClick	boolean	If should close the modal on click	🚫	false

ModalContent

Props

All props of section JSX element.

ModalFooter

Props

All props of footer JSX element.

Do’s

1. Keep it simple. The content of a modal should represent one, clear action from the user - even if it takes multiple steps to be completed.
2. Always use a modal to confirm any destructive actions.
3. Modals are not the same as error, success, or warning messages. Assess the information that goes within it, what action it is triggering, and if a modal is really necessary.
4. Avoid nesting modals.

👉 For UX Writing guidelines, access https://uxwriting.vtex.com

• Behavior
• Examples
  • Sizes