Playbook Design System

Default

Overlays help shift focus by dimming or masking background content. This kit supports gradient and solid color modes, with adjustable opacity to suit the context.

import React from 'react'

import { Overlay, Table } from 'playbook-ui'

const TableExample = () => {
    return (
        <Table size="sm">
            <thead>
                <tr>
                    <th>{'Column 1'}</th>
                    <th>{'Column 2'}</th>
                    <th>{'Column 3'}</th>
                    <th>{'Column 4'}</th>
                    <th>{'Column 5'}</th>
                </tr>
            </thead>
            <tbody>
                {Array.from({ length: 7 }, (_, index) => (
                    <tr key={index}>
                        {Array.from({ length: 5 }, (_, columnIndex) => (
                            <td key={columnIndex}>{`Value ${columnIndex + 1}`}</td>
                        ))}
                    </tr>
                ))}
            </tbody>
        </Table>
    )
}

const OverlayDefault = () => (
    <>
        <Overlay>
            <TableExample />
        </Overlay>
    </>
)

export default OverlayDefault

Gradient & Opacity

By default, the overlay is rendered as a gradient. Setting the gradient prop to false renders the overlay as a solid color. You can adjust the transparency of the solid overlay by using the opacity prop.

import React from 'react'

import { Overlay, Image, Flex } from 'playbook-ui'

const OverlayGradientOpacity = () => (
    <Flex
        justify="around"
        wrap
    >
        <Overlay
            gradient={false}
            marginBottom="xxs"
            opacity="opacity_2"
        >
          <Image
              alt="picture of a misty forest"
              display="block"
              maxWidth="100%"
              url="https://unsplash.it/500/400/?image=634"
          />
        </Overlay>
        <Overlay
            gradient={false}
            marginBottom="xxs"
            opacity="opacity_8"
        >
          <Image
              alt="picture of a misty forest"
              display="block"
              maxWidth="100%"
              url="https://unsplash.it/500/400/?image=634"
          />
        </Overlay>
    </Flex>
)

export default OverlayGradientOpacity

Color

The color prop is used to change the color of the solid or gradient mask. Gradient overlays always start opaque and fade to transparent.

NOTE: Images are set to display: block to remove the default inline spacing caused by line height. This ensures the image fully fills the container without unexpected gaps.

import React from 'react'

import { Overlay, Image, Flex } from 'playbook-ui'

const OverlayColor = () => (
    <Flex
        justify="around"
        wrap
    >
        <Overlay
            color="black"
            marginBottom="xxs"
        >
          <Image
              alt="picture of a misty forest"
              display="block"
              size="xl"
              url="https://unsplash.it/500/400/?image=634"
          />
        </Overlay>
        <Overlay
            color="black"
            gradient={false}
            marginBottom="xxs"
            opacity="opacity_4"
        >
          <Image
              alt="picture of a misty forest"
              display="block"
              size="xl"
              url="https://unsplash.it/500/400/?image=634"
          />
        </Overlay>
        <Overlay
            color="error"
            marginBottom="xxs"
        >
          <Image
              alt="picture of a misty forest"
              display="block"
              size="xl"
              url="https://unsplash.it/500/400/?image=634"
          />
        </Overlay>
        <Overlay
            color="error"
            gradient={false}
            marginBottom="xxs"
            opacity="opacity_4"
        >
          <Image
              alt="picture of a misty forest"
              display="block"
              size="xl"
              url="https://unsplash.it/500/400/?image=634"
          />
        </Overlay>
    </Flex>
)

export default OverlayColor

Layout

The optional layout prop accepts the position and size of the overlay as a key:value pair.

The position key accepts bottom (default), top, y (for both top and bottom) right, left, or x (for both left and right), which sets the side(s) where the color overlay starts. The direction of the overlay is always toward the opposite side of the position. For example, the default position of bottom starts the overlay on the bottom edge of your container and extends it toward the opposite side: the top.

The size value is full (100%) by default, but accepts our spacing tokens or a percentage value as a string, and literally translates to how much of the container is covered by the overlay(s).

import React from 'react'

import { Overlay, Table } from 'playbook-ui'

const TableExample = () => {
    return (
        <Table size="sm">
            <thead>
                <tr>
                    <th>{'Column 1'}</th>
                    <th>{'Column 2'}</th>
                    <th>{'Column 3'}</th>
                    <th>{'Column 4'}</th>
                    <th>{'Column 5'}</th>
                </tr>
            </thead>
            <tbody>
                {Array.from({ length: 7 }, (_, index) => (
                    <tr key={index}>
                        {Array.from({ length: 5 }, (_, columnIndex) => (
                            <td key={columnIndex}>{`Value ${columnIndex + 1}`}</td>
                        ))}
                    </tr>
                ))}
            </tbody>
        </Table>
    )
}

const OverlayLayout = () => (
    <>
        <Overlay layout={{ y: "xl" }}>
            <TableExample />
        </Overlay>
    </>
)

export default OverlayLayout

Multi-directional

Optionally, you can pass multi-directional options (x or y) to the position key, which creates multiple overlays.

Your color is still applied as the starting edge to both overlays, and each mask will fade to transparent moving toward its opposite edge, ending at the size value you set.

NOTE: Multi-directional overlays share the available container space, so passing full or a percentage string greater than 50% to a multi-directional overlay will cause your masks to overlap at the midline of your container. As a best practice, we do not recommend exceeding a percentage size of 25% when using multi-directional overlays.

import React from 'react'

import { Overlay, Card, Flex, FlexItem } from 'playbook-ui'

const InlineCardsExample = () => {
    return (
        <Flex
            columnGap="lg"
            orientation="row"
            overflowX="auto"
        >
            {Array.from({ length: 15 }, (_, index) => (
                <FlexItem key={index}>
                    <Card>{"Card Content"}</Card>
                </FlexItem>
            ))}
        </Flex>
    )
}

const OverlayMultiDirectional = () => (
    <>
        <Overlay
            color="card_light"
            layout={{"x": "xl"}}
        >
            <InlineCardsExample />
        </Overlay>
    </>
)

export default OverlayMultiDirectional

Vertical Dynamic Multi-directional

Pass the dynamic prop to make the overlay render while the scrollbar isn't at either end on the scrollbar.

import React, { forwardRef } from 'react'

import { Overlay, Card, Flex, FlexItem } from 'playbook-ui'

const InlineCardsExample = forwardRef(function InlineCardsExample(ref) {
    return (
        <Flex
            columnGap="lg"
            orientation="row"
            ref={ref}
        >
            {Array.from({ length: 15 }, (_, index) => (
                <FlexItem key={index}>
                    <Card>{"Card Content"}</Card>
                </FlexItem>
            ))}
        </Flex>
    )
})

const OverlayVerticalDynamicMultiDirectional = () => (
    <>
        <Overlay
            color="card_light"
            dynamic
            layout={{"x": "xl"}}
        >
            <InlineCardsExample />
        </Overlay>
    </>
)

export default OverlayVerticalDynamicMultiDirectional

Toggle

To toggle an overlay, add a button with an event handler. Remove the overlay container to reveal the underlying content. Re-wrap the overlay container to add the overlay back.

/* eslint-disable react/no-multi-comp */
import React, { useState } from "react";

import { Overlay, Button, Table } from 'playbook-ui'

const TableExample = () => {
    return (
        <Table size="sm">
            <thead>
                <tr>
                    <th>{"Column 1"}</th>
                    <th>{"Column 2"}</th>
                    <th>{"Column 3"}</th>
                    <th>{"Column 4"}</th>
                    <th>{"Column 5"}</th>
                </tr>
            </thead>
            <tbody>
                {Array.from({ length: 7 }, (_, index) => (
                    <tr key={index}>
                        {Array.from({ length: 5 }, (_, columnIndex) => (
                            <td key={columnIndex}>{`Value ${columnIndex + 1}`}</td>
                        ))}
                    </tr>
                ))}
            </tbody>
        </Table>
    );
};

const OverlayToggle = () => {
    const [showOverlay, setShowOverlay] = useState(true);

    return (
        <>
            {showOverlay ? (
                <>
                    <Overlay overflow="hidden">
                        <div style={{ height: 200 }}>
                            <TableExample />
                        </div>
                    </Overlay>
                    <Button
                        fullWidth
                        icon="chevron-down"
                        iconRight
                        key="chevron-down"
                        onClick={() => setShowOverlay(false)}
                        text="Show More"
                        variant="link"
                    />
                </>
            ) : (
                <>
                    <TableExample />
                    <Button
                        fullWidth
                        icon="chevron-up"
                        iconRight
                        key="chevron-up"
                        onClick={() => setShowOverlay(true)}
                        text="Show Less"
                        variant="link"
                    />
                </>
            )}
        </>
    );
};

export default OverlayToggle;

Hide Scroll Bar

Pass the scrollBarNone prop to hide the scrollbar from view. This is particularly helpful for small containers where the scrollbar may occupy too much space.

import React from 'react'

import { Overlay, Card, Flex, FlexItem } from 'playbook-ui'

const InlineCardsExample = () => {
    return (
        <Flex
            columnGap="lg"
            orientation="row"
            overflowX="auto"
        >
            {Array.from({ length: 15 }, (_, index) => (
                <FlexItem key={index}>
                    <Card>{"Card Content"}</Card>
                </FlexItem>
            ))}
        </Flex>
    )
}

const OverlayHideScrollBar = () => (
    <>
        <Overlay
            color="card_light"
            layout={{"x": "xl"}}
            scrollBarNone
        >
            <InlineCardsExample />
        </Overlay>
    </>
)

export default OverlayHideScrollBar

Full Page Opacity

To enable the overlay to cover the full size of your screen, you can pass the fullScreen prop. You can also pass an opacity along with it.

import React, { useState } from 'react'

import { Overlay, Button, FixedConfirmationToast } from 'playbook-ui'

const OverlayFullscreenOpacity = () => {
  const [openOpacity40, setOpenOpacity40] = useState(false)
  const [openOpacity80, setOpenOpacity80] = useState(false)

  const handleClickOpacity40 = () => {
    setOpenOpacity40(true)
  }
  const handleCloseOpacity40 = () => {
    setOpenOpacity40(false)
  }

  const handleClickOpacity80 = () => {
    setOpenOpacity80(true)
  }
  const handleCloseOpacity80 = () => {
    setOpenOpacity80(false)
  }

  return (
    <>
      <div>
        <Button
            onClick={handleClickOpacity40}
            text="40% Opacity"
            variant="secondary"
        />
        {' '}
        <Button
            onClick={handleClickOpacity80}
            text="80% Opacity"
            variant="secondary"
        />

        {openOpacity40 && (
            <Overlay
                fullScreen
                gradient={false}
                opacity="opacity_4"
            >
              <FixedConfirmationToast
                  closeable
                  horizontal='center'
                  onClose={handleCloseOpacity40}
                  open={openOpacity40}
                  status="tip"
                  text='Fullscreen Overlay at 40% Opacity.'
                  vertical='top'
              />
            </Overlay>
        )}

        {openOpacity80 && (
            <Overlay
                fullScreen
                gradient={false}
                opacity="opacity_8"
            >
              <FixedConfirmationToast
                  closeable
                  display="block"
                  horizontal='center'
                  onClose={handleCloseOpacity80}
                  open={openOpacity80}
                  status="tip"
                  text='Fullscreen Overlay at 80% Opacity.'
                  vertical='top'
              />
            </Overlay>
        )}
      </div>
    </>
  )
}

export default OverlayFullscreenOpacity

Full Page Using Background Color Tokens

The fullScreen prop also allows you to use color along with it.

import React, { useState } from 'react'

import { Overlay, Button, FixedConfirmationToast } from 'playbook-ui'

const OverlayFullscreenBackground = () => {
  const [openBackground, setOpenBackground] = useState(false)

  const handleClickBackground = () => {
    setOpenBackground(true)
  }

  const handleCloseBackground = () => {
    setOpenBackground(false)
  }

  return (
    <>
      <div>
        <Button
            onClick={handleClickBackground}
            text="Background Dark"
            variant="secondary"
        />

        {openBackground && (
          <Overlay
              color="bg_dark"
              fullScreen
              gradient={false}
              opacity="opacity_4"
          >
            <FixedConfirmationToast
                closeable
                horizontal='center'
                onClose={handleCloseBackground}
                open={openBackground}
                status="tip"
                text='Fullscreen Overlay with color set to Background Dark.'
                vertical='top'
            />
          </Overlay>
        )}
      </div>
    </>
  )
}

export default OverlayFullscreenBackground

Overlay

Available Props

Contribute to Playbook

Power

Connect