Creates a fixed position overlay with entrance and exit animation. There are two variants:

Image Overlay: uses a built in image slot, which renders visually like a dialog in desktop viewports. The image layout is handled automatically. This version is triggered by providing an imagePath in the props.

Standard Overlay: When not using the imagePath prop, the overlay simply renders its children. In mobile viewports, the Overlay covers the entire screen. In desktop viewports, there are configuration options for which part of the viewport to cover. Overlay uses the FocusBoomerang utility to manage focus correctly when opened and closed; consumers will need to take care of preventing focus to content covered by the Overlay.

If the consumer can place the Overlay in a spot in the DOM which permits the fixed positioning to work correctly, the Overlay may be used as is. If there are positioning or layering issues due to being nested in a positioned element, the consumer may choose to use the Layer component to facilitate positioning correctly.

To get exit animation, the content/children of Overlay should be removed before the Overlay itself. If the Overlay is able to be mounted at all times, entrance and exit animations will always work.


  • alignmentoneOf('fullscreen', 'right', 'left', 'rightCrate', 'leftCrate', 'rightThird', 'leftThird')['rightCrate']

    Indicates what portion of the UI is covered in desktop viewports. Only applicable when not using the imagePath option. DEPRECATION WARNING: 'left' and 'right' will be removed in an upcoming version. Please use leftCrate or rightCrate if you expect your overlay to cover the left crate or the right crate.

  • childrenany

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

  • childrenContainerClassNamestring

    Classname passed to the element that wraps the children

  • closeCallbackfunc[() => {}]

    Function attached to the click event of the included close button.

  • closePropsobject[{}]

    Props passed to the CloseButton component within the Overlay.

  • containerPropsobject

    Additional props to be spread on the container HTMLElement.

  • focusOnOpenbool[true]

    When true, focus will be placed on the container div of the overlay when opened, permitting seamless keyboard traversal. When false, the consumer is expected to manage focus.

  • 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')['cover']

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

  • renderCloseButtonbool[true]

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

  • showMaskbool[true]

    Whether to show a mask when the overlay is opened.

  • styleobject

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

  • topShadowbool[false]

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

Standard Overlay

Overlay with optional image included