Overlay#

The Overlay component inheritely uses the Modal component, however its focus is not trapped, it is not rendered in a portal and the background is scrollable.

Import#

import { Overlay } from 'bumbag';

Usage#

Editable example

<Overlay.State>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay><Box>Hello world</Box></Overlay>
</Overlay.State>

<Overlay.State>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay><Box>Hello world</Box></Overlay>
</Overlay.State>

Composition#

The Overlay component comes with utilities to compose with other components.

`use`#

Editable example

<Overlay.State>
  <Overlay.Disclosure use={Button}>Open overlay</Overlay.Disclosure>
  <Overlay backgroundColor="white" border="1px solid black" padding="major-2">
    Hello world
    <Overlay.Disclosure use={Button}>Close overlay</Overlay.Disclosure>
  </Overlay>
</Overlay.State>

<Overlay.State>
  <Overlay.Disclosure use={Button}>Open overlay</Overlay.Disclosure>
  <Overlay backgroundColor="white" border="1px solid black" padding="major-2">
    Hello world
    <Overlay.Disclosure use={Button}>Close overlay</Overlay.Disclosure>
  </Overlay>
</Overlay.State>

Hooks#

Editable example

function Example() {
  const overlay = Overlay.useState()
  const overlayProps = Overlay.useProps({ ...overlay });
  const overlayDisclosureProps = Overlay.Disclosure.useProps({ ...overlay });

  return (
    <div>
      <Button {...overlayDisclosureProps}>Open overlay</Button>
      <Box {...overlayProps} backgroundColor="white" border="1px solid black" padding="major-2">
        Hello world
        <Button {...overlayDisclosureProps}>Close overlay</Button>
      </Box>
    </div>
  )
}

function Example() {
  const overlay = Overlay.useState()
  const overlayProps = Overlay.useProps({ ...overlay });
  const overlayDisclosureProps = Overlay.Disclosure.useProps({ ...overlay });

  return (
    <div>
      <Button {...overlayDisclosureProps}>Open overlay</Button>
      <Box {...overlayProps} backgroundColor="white" border="1px solid black" padding="major-2">
        Hello world
        <Button {...overlayDisclosureProps}>Close overlay</Button>
      </Box>
    </div>
  )
}

Render props#

Editable example

<Overlay.State>
  <Overlay>
    {overlayProps => (
      <Overlay.Disclosure>
        {overlayDisclosureProps => (
          <React.Fragment>
            <Button {...overlayDisclosureProps}>Open overlay</Button>
            <Box {...overlayProps} backgroundColor="white" border="1px solid black" padding="major-2">
              Nesting for dayzzz
              <Button {...overlayDisclosureProps}>Close</Button>
            </Box>
          </React.Fragment>
        )}
      </Overlay.Disclosure>
    )}
  </Overlay>
</Overlay.State>

<Overlay.State>
  <Overlay>
    {overlayProps => (
      <Overlay.Disclosure>
        {overlayDisclosureProps => (
          <React.Fragment>
            <Button {...overlayDisclosureProps}>Open overlay</Button>
            <Box {...overlayProps} backgroundColor="white" border="1px solid black" padding="major-2">
              Nesting for dayzzz
              <Button {...overlayDisclosureProps}>Close</Button>
            </Box>
          </React.Fragment>
        )}
      </Overlay.Disclosure>
    )}
  </Overlay>
</Overlay.State>

Placement#

Change where your overlay is positioned with the placement prop.

Editable example

<Overlay.State>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay placement="top">Hello world</Overlay>
</Overlay.State>

<Overlay.State>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay placement="top">Hello world</Overlay>
</Overlay.State>

Animation#

Fade#

Editable example

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade>Hello world</Overlay>
</Overlay.State>

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade>Hello world</Overlay>
</Overlay.State>

Slide#

Editable example

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade slide>Hello world</Overlay>
</Overlay.State>

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade slide>Hello world</Overlay>
</Overlay.State>

Expand#

Editable example

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade expand>Hello world</Overlay>
</Overlay.State>

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade expand>Hello world</Overlay>
</Overlay.State>

Duration#

Editable example

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade duration="100ms" fade>Hello world</Overlay>
</Overlay.State>

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay fade duration="100ms" fade>Hello world</Overlay>
</Overlay.State>

Placement with animation#

Editable example

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay placement="top" fade slide>Hello world</Overlay>
</Overlay.State>

<Overlay.State animated>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay placement="top" fade slide>Hello world</Overlay>
</Overlay.State>

Restricting closure#

You can restrict closure with either the hideOnEsc or hideOnClickOutside prop.

Editable example

<Overlay.State>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay hideOnEsc={false} hideOnClickOutside={false}>
    Hello world
    <Overlay.Disclosure use={Button}>Close overlay</Overlay.Disclosure>
  </Overlay>
</Overlay.State>

<Overlay.State>
  <Overlay.Disclosure>Open overlay</Overlay.Disclosure>
  <Overlay hideOnEsc={false} hideOnClickOutside={false}>
    Hello world
    <Overlay.Disclosure use={Button}>Close overlay</Overlay.Disclosure>
  </Overlay>
</Overlay.State>

Controlled#

Editable example

function Example() {
  const overlay = Overlay.useState();

  return (
    <React.Fragment>
      <Overlay.Disclosure {...overlay}>Open overlay</Overlay.Disclosure>
      <Overlay {...overlay}>
        Hello world
        <Overlay.Disclosure use={Button} {...overlay}>Close overlay</Overlay.Disclosure>
      </Overlay>
    </React.Fragment>
  )
}

function Example() {
  const overlay = Overlay.useState();

  return (
    <React.Fragment>
      <Overlay.Disclosure {...overlay}>Open overlay</Overlay.Disclosure>
      <Overlay {...overlay}>
        Hello world
        <Overlay.Disclosure use={Button} {...overlay}>Close overlay</Overlay.Disclosure>
      </Overlay>
    </React.Fragment>
  )
}

Accessibility#

Rules#

A Overlay must have an accompanying Overlay.Disclosure component.

Patterns#

Overlay extends the accessibility features of the Modal component.

Props#

Overlay Props#

9 state props

These props are returned by the state hook. You can spread them into this component (...state) or pass them separately. You can also provide these props from your own state logic.

baseId string

ID that will serve as a base for all the items IDs.

visible boolean

Whether it's visible or not.

animating boolean

Whether it's animating or not.

animated number | boolean

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

stopAnimation () => void

Stops animation. It's called automatically if there's a CSS transition.

modal boolean

Toggles Dialog's modal state.

Non-modal: preventBodyScroll doesn't work and focus is free.
Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.

hide () => void

Changes the visible state to false

baseId string Required

ID that will serve as a base for all the items IDs.

Inherits Modal props

hideBackdrop boolean

Hides the backdrop.

placement

"top-start"
  | "top"
  | "top-end"
  | "right-start"
  | "right"
  | "right-end"
  | "bottom-end"
  | "bottom"
  | "bottom-start"
  | "left-end"
  | "left"
  | "left-start"
  | "center"

Sets the placement of the modal.

delay string

Delay of the animation (in s/ms).

duration string

Duration of the animation (in s/ms).

expand

boolean
  | "top"
  | "right"
  | "bottom"
  | "left"
  | "center"

Will the component have an expand animation when it is toggled on/off?

fade boolean

Will the component have a fade animation when it is toggled on/off?

slide boolean | "top" | "right" | "bottom" | "left"

Will the component have a slide animation when it is toggled on/off?

timingFunction string

Timing function of the animation

hideOnEsc boolean

When enabled, user can hide the dialog by pressing Escape.

hideOnClickOutside boolean

When enabled, user can hide the dialog by clicking outside it.

preventBodyScroll boolean

When enabled, user can't scroll on body when the dialog is visible. This option doesn't work if the dialog isn't modal.

Inherits Box props

use

string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })

className string

children

string
  | number
  | boolean
  | {}
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<...>)>
  | ReactNodeArray
  | ReactPortal
  | ((props: BoxProps) => ReactNode)

alignX "right" | "left" | "center"

alignY "top" | "bottom" | "center"

variant string

colorMode string

disabled boolean

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 95 more ...;
  Template?: TemplateThemeConfig;
}

elementRef ((instance: any) => void) | RefObject<any>

themeKey string

Overlay.Disclosure Props#

5 state props

These props are returned by the state hook. You can spread them into this component (...state) or pass them separately. You can also provide these props from your own state logic.

visible boolean

Whether it's visible or not.

baseId string Required

ID that will serve as a base for all the items IDs.

toggle () => void Required

Toggles the visible state

toggle () => void Required

Toggles the visible state

Inherits ModalDisclosure props

disabled boolean

Same as the HTML attribute.

focusable boolean

When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

Inherits Box props

use

string
  | (ComponentClass<any, any> & { useProps: any; })
  | (FunctionComponent<any> & { useProps: any; })

className string

children

string
  | number
  | boolean
  | {}
  | ReactElement<any, string
  | ((props: any) => ReactElement<any, string
  | ...
  | (new (props: any) => Component<any, any, any>)>)
  | (new (props: any) => Component<...>)>
  | ReactNodeArray
  | ReactPortal
  | ((props: BoxProps) => ReactNode)

alignX "right" | "left" | "center"

alignY "top" | "bottom" | "center"

variant string

colorMode string

overrides

{
  useCSSVariables?: boolean;
  altitudes?: AltitudesThemeConfig;
  borders?: BordersThemeConfig;
  borderRadii?: BorderRadiiThemeConfig;
  ... 95 more ...;
  Template?: TemplateThemeConfig;
}

elementRef ((instance: any) => void) | RefObject<any>

themeKey string

State#

Overlay.State API#

baseId string

ID that will serve as a base for all the items IDs.

visible boolean

Whether it's visible or not.

animated number | boolean

modal boolean

Toggles Dialog's modal state.

Non-modal: preventBodyScroll doesn't work and focus is free.
Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.

Overlay.State Return Values#

15 values

baseId string Required

ID that will serve as a base for all the items IDs.

visible boolean Required

Whether it's visible or not.

animated number | boolean Required

animating boolean Required

Whether it's animating or not.

setBaseId (value: SetStateAction<string>) => void Required

Sets baseId.

show () => void Required

Changes the visible state to true

hide () => void Required

Changes the visible state to false

toggle () => void Required

Toggles the visible state

setVisible (value: SetStateAction<boolean>) => void Required

Sets visible.

setAnimated (value: SetStateAction<number | boolean>) => void Required

Sets animated.

stopAnimation () => void Required

Stops animation. It's called automatically if there's a CSS transition.

modal boolean Required

Toggles Dialog's modal state.

Non-modal: preventBodyScroll doesn't work and focus is free.
Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.

setModal (value: SetStateAction<boolean>) => void Required

Sets modal.

Overlay.useState API#

baseId string

ID that will serve as a base for all the items IDs.

visible boolean

Whether it's visible or not.

animated number | boolean

modal boolean

Toggles Dialog's modal state.

Non-modal: preventBodyScroll doesn't work and focus is free.
Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.

Overlay.useState Return Values#

15 values

baseId string Required

ID that will serve as a base for all the items IDs.

visible boolean Required

Whether it's visible or not.

animated number | boolean Required

animating boolean Required

Whether it's animating or not.

setBaseId (value: SetStateAction<string>) => void Required

Sets baseId.

show () => void Required

Changes the visible state to true

hide () => void Required

Changes the visible state to false

toggle () => void Required

Toggles the visible state

setVisible (value: SetStateAction<boolean>) => void Required

Sets visible.

setAnimated (value: SetStateAction<number | boolean>) => void Required

Sets animated.

stopAnimation () => void Required

Stops animation. It's called automatically if there's a CSS transition.

modal boolean Required

Toggles Dialog's modal state.

Non-modal: preventBodyScroll doesn't work and focus is free.
Modal: preventBodyScroll is automatically enabled, focus is trapped within the dialog and the dialog is rendered within a Portal by default.

setModal (value: SetStateAction<boolean>) => void Required

Sets modal.

Theming#

Overlay.styles.base

Overlay.styles.placements.center

Overlay.styles.placements.left

Overlay.styles.placements.right

Overlay.styles.placements.top

Overlay.styles.placements.bottom

Overlay.styles.placements.topStart

Overlay.styles.placements.topEnd

Overlay.styles.placements.bottomStart

Overlay.styles.placements.bottomEnd

Overlay.Disclosure.styles.base

On this page

Overlay#

Import#

Usage#

Composition#

use#

Hooks#

Render props#

Placement#

Animation#

Fade#

Slide#

Expand#

Duration#

Placement with animation#

Restricting closure#

Controlled#

Accessibility#

Rules#

Patterns#

Props#

Overlay Props#

Overlay.Disclosure Props#

State#

Overlay.State API#

Overlay.State Return Values#

Overlay.useState API#

Overlay.useState Return Values#

Theming#

`use`#