HomeStarbucks Pattern Library



Creates a fixed position overlay to be used in conjunction with ModalProvider. Overlay does not create a mask or manage focus; to get an accessible modal overlay with a mask see ModalProvider documentation.

In mobile viewports, the overlay covers the entire viewport. In desktop, user can choose from a variety of presets for what portion of the viewport will cover. See prop options below.

The overlay comes with an optional close button which will automatically close the modal when used in conjunction with the ModalProvider component.

In your Overlay's content, please include a heading for accessibility; the heading level should be an h2 (as it is expected that you have an h1 on the page already).


  • alignmentoneOf('dialog', 'dialog-lg', 'fullscreen', 'rightCrate', 'leftCrate', 'rightThird', 'leftThird')

    Indicates what portion of the UI is covered in desktop viewports.

  • childrenany

    Nested component(s) which become the content of the overlay.

  • childrenContainerClassNamestring

    Classname passed to the element that wraps the children

  • closeCallbackfunc

    Optional function to run when the overlay is closing.

  • closePropsobject

    Props passed to the CloseButton component within the Overlay.

  • containerPropsobject

    Additional props to be spread on the container HTMLElement.

  • contentPropsobject

    Additional props to be spread on the content HTMLElement.

  • imageAltstring

    Prop to allow for giving alternate text to the image

  • imageContainerPropsobject

    Props to pass into the container around the image

  • imagePathstring

    Optional prop to allow for image to be placed on top of the Overlay.

  • permitImageToShrinkbool

    Optional prop to allow for a top-image to be responsive. This is useful when you have tall content and a scalable image. Only applicable if imagePath is passed.

  • imageObjectFitoneOf('cover', 'contain', 'fill', 'scale-down')

    Optional prop to control the object-fit of the top image. Only applicable if imagePath is passed and permitImageToShrink is true.

  • renderCloseButtonbool

    Whether to use the included default CloseButton component. If false, consumer is expected to provide a custom close button in the child component.

  • styleobject

    Optional style object for custom styling such as z-index; applied to the outermost div.

  • topShadowbool

    A CSS box shadow intended for situations in which another container is visually 'above' the overlay.

  • useLegacyOverlay[false]

Example: Standard overlay

Example: Overlay using Dialog alignment

Example: Overlay using Dialog alignment with an image

Example: (Deprecated) Standard Overlay

Example: (Deprecated) Overlay with optional image included