React SDK

Modal (Dialog)

A dialog is a window overlaid on either the primary window or another dialog window. Contents behind a modal dialog are inert meaning that users cannot interact with content behind the dialog.

Import

Usage

When the modal opens, focus is sent into the modal and set to the first tabbable element. If there are no tabbled element, focus is set on the ModalContent.

Editable Example

Close Modal on Overlay Click

By default, the modal closes when you click it's overlay. You can set closeOnOverlayClick to false if you want the modal to stay visible.

Editable Example

Block Scrolling when Modal opens

For accessibility, it's recommended to block scrolling on the main document behind the modal. Search.io does this by default but you can set blockScroll to false to allow scrolling behind modal.

Editable Example

Center Modal Content

By default, the modal content is centered on screens. You can set center to false if you want to keep the dialog on top of the page.

Editable Example

Pass the size prop if you need to adjust the size of the modal. Values can be any of the following:

ValueMax Width
max-w-xs20rem
max-w-sm24rem
max-w-md28rem
max-w-lg32rem
max-w-xl36rem
max-w-2xl42rem
max-w-3xl48rem
max-w-4xl56rem
max-w-5xl64rem
max-w-6xl72rem
max-w-7xl80rem
max-w-screen-sm640px
max-w-screen-md768px
max-w-screen-lg1024px
max-w-screen-xl1280px
max-w-screen-2xl1536px
max-w-full100%
Editable Example

    Making other elements Inert

    When the modal is open, it's rendered within a portal and all it's siblings have aria-hidden set to true so the only thing screen readers see is the modal. To disable this behavior, set useInert to false.

    Accessibility

    Keyboard and Focus Management

    • When the modal opens, focus is trapped within it.
    • Clicking on the overlay closes the Modal.
    • Pressing Esc closes the Modal.
    • Scrolling is blocked on the elements behind the modal.
    • The modal is portalled to the end of document.body to break it out of the source order and make it easy to add aria-hidden to its siblings.

    ARIA

    • The ModalContent has aria-modal set to true.
    • The ModalContent has aria-labelledby set to the id of the ModalTitle
    • The ModalContent has aria-describedby set to the id of the ModalBody

    Props

    NameTypeDefaultDescription
    openbooleanIf true, the modal will open
    onClose(event) => voidCallback invoked to close the modal.
    useInertbooleantrueA11y: If true, all elements behing the Modal will have aria-hidden set to true so that screen readers can only see the Modal.
    idstringThe id of the modal.
    ariaLabelledbystringARIA label for the modal.
    ariaDescribedbystringARIA description for the modal.
    fullWidthbooleanfalseIf true, the width of the content will be full screen.
    fullHeightbooleanfalseIf true, the height of the content will be full screen.
    closeOnEscbooleantrueIs the modal closable when user press esc key.
    closeOnOverlayClickbooleantrueIs the modal closable when user click on overlay.
    blockScrollbooleantrueWhether to block scrolling when dialog is open.
    centerbooleantrueShould the modal content be centered.
    trapFocusbooleantrueWhen the modal is open, trap focus within it.
    initialFocusRefReact.RefThe ref of the element to receive focus when the dialog opens
    finalFocusRefReact.RefThe ref of element to receive focus when the dialog closes
    returnFocusOnClosebooleantrueIf true, the modal will return focus to the element that triggered it when it closes.
    containerElementThe container where the portal will be rendered inside.
    sizestringmdThe width for the modal content.
    modalIdstringid attribute for modal.
    onEscKeyDown(event) => voidCallback fired when the escape key is pressed.
    onOverlayClick(event) => voidCallback fired when the overlay is clicked.
    onAnimationEnd() => voidCallback fired when the Modal has exited and the animation is finished.
    zIndex21474836472147483647z-index of the modal.