Thumbprint logo

Modal

Overlays to provide highly contextually user guidance

Usage

Modal dialogs appear as an overlay on a page. They should be used when Thumbtack requires a user response or needs to explain critical information without losing context of the page beneath it.

Use for sign ups
When to use

Use when you want a user to confirm an important action or to get information like signing up or logging in. Since modals do interrupt a users’ experience, they could be perceived as annoying or bothersome and should be used with discretion.

Use for sign ups
When not to use

Do not use a modal without a trigger from the user, for example on page load. Also, do not use if there is a modal already being displayed.

Behavior

Arrival

How modals arrive is just as important as the content they contain. Animation does more than provide a visually pleasing experience. They indicate to the user that there is something on top of the content they are interacting with.

Dismissing

By default, modals can be closed by clicking on the “x” in the upper right hand corner of the container or by clicking anywhere outside of the container which is called the “curtain”. The animation of the arrival is used, just in reverse.

Autofocus

By default, the focus is placed on the first item a user can select, allowing them to quickly select the requested information, or submit the modal.

Anatomy

Modal component anatomy

Modal Types

Modals are offered in three types to best suit the user experience needs.

Default

Standard dialog that temporarily overlays the main content of a digital interface to present additional information, options, or interactive elements to the user within the current context of the experience.

Promo

Visually engaging modal approach used to be part of a marketing strategy to drive user engagement and conversions by grabbing the user’s attention through strong visual headers.

Confirmation

Clear and concise options to confirm or cancel the action, providing a moment for the user to review their decision before proceeding.

Default

Standard dialog that temporarily overlays the main content of a digital interface to present additional information, options, or interactive elements to the user within the current context of the experience.

look of promo modal
Only delivered in 624 size

Sizing options

Modals are offered in multiple widths for the large responsive breakpoint or desktop experience. Selection of sizing should is dependent on the intended use case.

NameSizeDescription
Default624Most commonly used content such as forms and contextual informational.
Small512Minimal content and basic messaging such as confirmation modals.
Medium740Complex illustration and information non-suitable for the default size.
Large1025Largely complex content and content such as tables, data etc.

Promo

Visually engaging modal approach used to be part of a marketing strategy to drive user engagement and conversions by grabbing the user’s attention through strong visual headers.

look of promo modal
Only delivered in 624 size

Confirmation

Typically appears after the user has initiated a significant action, such as deleting a file, submitting a form, or completing a purchase, to ensure that the user understands the consequences of their action and to prevent accidental mistakes.

look of promo modal
Only delivered in 512 size

Best practices

Arrival

How modals arrive is just as important as the content they contain. Animation does more than provide a visually pleasing experience. They indicate to the user that there is something on top of the content they are interacting with.

Dismissing

By default, modals can be closed by clicking on the “x” in the upper right hand corner of the container or by clicking anywhere outside of the container which is called the “curtain”. The animation of the arrival is used, just in reverse.

Autofocus

By default, the focus is placed on the first item a user can select, allowing them to quickly select the requested information, or submit the modal.

Accessibility

Autofocus

By default, the focus is placed on the first item a user can select, allowing them to quickly select the requested information, or submit the modal.

Esc to close

In addition do dismissible actions (if applicable) the user should be able to close the modal experience with their keyboard using the esc key.

Focus Trap

The user should be able to tab through the interactive elements within the modal and cycle through each option without leaving the context until the modal is dismissed.

Role

The modal container should apple role=”dialog” to provide approach guidance for assistive technology tools. If immediate attention is needed (confirmation modal), then the role=”alertdialog” role may be necessary (read more about the alert dialog role).

Color contrast ratios

Content within the modal should abide by Thumbprint’s general policy for compliance for color contrast ratios.

Content Design

Writing for modals

Context is key. There needs to be a direct connection between the trigger (i.e. a button or link) and the modal that follows. This can be achieved by directly repeating the words of the trigger or using related terms. Maintaining a sense of connection between the CTA and modal transition is important to keep and maintain a consistent user experience.

Changelog

DateVersionNotes
Jun 30, 20252.0.0
  • Support for Default, Promo, and Confirmation types
  • Modernizes design approach
Nov 11, 20181.0.0Initial Release

Props

Modal

  • onCloseClick
    required

    Function that fires to close the modal.

    Type
    () => void
  • children

    Content that appears within the modal.

    Type
    React.ReactNode
  • onOpenFinish

    Function that fires once the modal has opened and transitions have ended.

    Type
    () => void
  • onCloseFinish

    Function that fires once the modal has closed and transitions have ended.

    Type
    () => void
  • shouldHideCloseButton

    Determines if the close button should be rendered. This is generally discouraged and should be used carefully. If used, the contents passed into the modal must contain a focusable element such as a link or button.

    Type
    boolean
  • shouldCloseOnCurtainClick

    Determines if the modal should close when clicking on the curtain, outside of the children.

    Type
    boolean
  • isOpen

    Should the modal appear open.

    Type
    boolean
  • width

    Sets the max-width of the modal container.

    Type
    'narrow' | 'medium' | 'wide'
  • heightAboveSmall

    Sets height of the modal container above small viewport. If auto (default), the modal height will be determined by its content. Otherwise, the modal height will be fixed at some constant px.

    Type
    'auto' | 'medium' | 'tall'

ModalHeader

  • children
    required

    Content (usually a ModalTitle and ModalDescription) that appears at the top of the modal.

    Type
    React.ReactNode

ModalTitle

  • children
    required

    Text that describes the modal contents. It is intended for use within the ModalHeader.

    Type
    string

ModalDescription

  • children
    required

    Text intended for use below a ModalTitle and within a ModalHeader.

    Type
    React.ReactNode

ModalContent

  • children
    required

    Content (usually a form) that makes up the main part of the modal.

    Type
    React.ReactNode

ModalContentFullBleed

  • children
    required

    Content (usually a form) that makes up the main part of the modal.

    Type
    React.ReactNode
  • className

    Allows the React className prop to be passed through to the rendered element.

    Type
    string
    Default
    ''
  • style

    Allows the React style prop to be passed through to the rendered element.

    Type
    React.CSSProperties
    Default
    {}

ModalFooter

  • children
    required

    Content (ususally buttons) to render within the footer.

    Type
    React.ReactNode
  • isSticky

    Attaches the footer to the bottom of the modal below the small breakpoint.

    Type
    boolean

ModalAnimatedWrapper

`ModalAnimatedWrapper` is an exported component that we export for developers that want access to `Modal` without padding and a close button. We export it as a named export instead of creating a `hasNoPadding` prop partly to discourage the use of `Modal` without padding. This component uses `ModalCurtain` and includes the backdrop, transition, and white modal wrapper that is available at a few widths.
  • onCloseClick
    required

    Function that fires to close the modal.

    Type
    () => void
  • children

    Content that appears within the modal.

    Type
    React.ReactNode
  • onOpenFinish

    Function that fires once the modal has opened and transitions have ended.

    Type
    () => void
  • onCloseFinish

    Function that fires once the modal has closed and transitions have ended.

    Type
    () => void
  • shouldCloseOnCurtainClick

    Determines if the modal should close when clicking on the curtain, outside of the children.

    Type
    boolean
    Default
    true
  • shouldPageScrollAboveSmall

    Allows the page to scroll vertically at viewports larger than the small breakpoint. If false, the modal will always be equal to or smaller than the viewport and the contents of the modal will scroll, not the page itself.

    Type
    boolean
    Default
    true
  • isOpen

    Should the modal appear open.

    Type
    boolean
    Default
    false
  • width

    Sets the max-width of the modal container.

    Type
    'narrow' | 'medium' | 'wide'
    Default
    'medium'
  • heightAboveSmall

    Sets height of the modal container above small viewport. If auto (default), the modal height will be determined by its content. Otherwise, the modal height will be fixed at some constant px.

    Type
    'auto' | 'medium' | 'tall'
    Default
    'auto'