AnchoredOverlay

AnchoredOverlay opens an Overlay relative to the anchor position.

Page navigation navigation

React

readyNot reviewed for a11y

AnchoredOverlay provides an anchor that will open a floating Overlay positioned relative to the anchor. The Overlay can be opened and navigated using a keyboard or mouse.

React examples

Default

import React from 'react'
import {AnchoredOverlay, Button} from '@primer/react'


export default function Default() {
  const [open, setOpen] = React.useState(false)


  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
    >
      <div>Anchored overlay content</div>
    </AnchoredOverlay>
  )
}

import React from 'react'
import {AnchoredOverlay, Button} from '@primer/react'

export default function Default() {
  const [open, setOpen] = React.useState(false)

  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
    >
      <div>Anchored overlay content</div>
    </AnchoredOverlay>
  )
}

Width and height customization

You can pick from a set of predefined widths and heights.

import React from 'react'
import {AnchoredOverlay, Button} from '@primer/react'


export default function WidthHeightCustom() {
  const [open, setOpen] = React.useState(false)


  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
      width="small"
      height="xsmall"
    >
      <div>Anchored overlay content</div>
    </AnchoredOverlay>
  )
}

import React from 'react'
import {AnchoredOverlay, Button} from '@primer/react'

export default function WidthHeightCustom() {
  const [open, setOpen] = React.useState(false)

  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
      width="small"
      height="xsmall"
    >
      <div>Anchored overlay content</div>
    </AnchoredOverlay>
  )
}

Custom positioning

The side, align, anchorOffset, and alignmentOffset props can be used to customize how the AnchoredOverlay is positioned relative to the "anchor" that toggles it.

import React from 'react'
import {AnchoredOverlay, Button} from '@primer/react'


export default function PositionCustom() {
  const [open, setOpen] = React.useState(false)


  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
      side="outside-right"
      align="end"
      anchorOffset={20}
      alignmentOffset={4}
    >
      <div>Anchored overlay content</div>
    </AnchoredOverlay>
  )
}

import React from 'react'
import {AnchoredOverlay, Button} from '@primer/react'

export default function PositionCustom() {
  const [open, setOpen] = React.useState(false)

  return (
    <AnchoredOverlay
      open={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      renderAnchor={props => <Button {...props}>Toggle overlay</Button>}
      side="outside-right"
      align="end"
      anchorOffset={20}
      alignmentOffset={4}
    >
      <div>Anchored overlay content</div>
    </AnchoredOverlay>
  )
}

More code examples

See the AnchoredOverlay Storybook stories.

Props

AnchoredOverlay

Name	Default	Description
open Required	`false`	`boolean` Determines whether the overlay portion of the component should be shown or not.
onOpen		`(gesture: 'anchor-click' \| 'anchor-key-press', event?: KeyboardEvent<HTMLElement> \| undefined) => unknown` A callback that is called whenever the overlay is currently closed and an "open gesture" is detected.
onClose		`(gesture: 'anchor-click' \| 'click-outside' \| 'escape') => unknown` A callback that is called whenever the overlay is currently open and a "close gesture" is detected.
renderAnchor		`<T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element` A custom function component used to render the anchor element. When renderAnchor is null, an anchorRef is required.
anchorRef		`React.RefObject<HTMLElement>` An override to the internal `renderAnchor` ref that will be used to position the overlay. When `renderAnchor` is `null`, this can be used to make an anchor that is detached from `AnchoredOverlay`.
anchorId		`string` An override to the internal id that will be passed to the anchor.
side	`'outside-bottom'`	`\| 'inside-top' \| 'inside-bottom' \| 'inside-left' \| 'inside-right' \| 'inside-center' \| 'outside-top' \| 'outside-bottom' \| 'outside-left' \| 'outside-right'`
align	`'start'`	`'start' \| 'center' \| 'end'`
alignmentOffset	`4`	`number` An additional offset, in pixels, to move the floating element from the aligning edge. Positive values move the floating element in the direction of center-alignment. Negative values move the floating element away from center-alignment. When align is `'center`, positive offsets move the floating element right (top or bottom anchor side) or down (left or right anchor side). If using outside positioning, or if `align` is set to `'center'`, this defaults to `0` instead of `4`.
anchorOffset	`4`	`number` The number of pixels between the anchor edge and the floating element. Positive values move the floating element farther from the anchor element (for outside positioning) or further inside the anchor element (for inside positioning). Negative values have the opposite effect. If `side` is set to `'inside-center'`, this defaults to `0` instead of `4`.
overlayProps		`Partial<OverlayProps>` Props to be spread on the internal `Overlay` component.
focusTrapSettings		`Partial<FocusTrapHookSettings>` Settings to apply to the focus trap on the internal `Overlay` component.
focusZoneSettings		`Partial<FocusZoneHookSettings>` Settings to apply to the focus zone on the internal `Overlay` component.
className		`string` Class name for custom styling.
preventOverflow	`true`	`boolean` Determines if the Overlay width should be adjusted responsively if there is not enough space to display the Overlay. If `preventOverflow` is set to `false`, the Overlay will be displayed at the maximum width that fits within the viewport.
height		`'small' \| 'initial' \| 'large' \| 'medium' \| 'auto' \| 'fit-content' \| 'xsmall' \| 'xlarge'`
width		`'small' \| 'large' \| 'medium' \| 'auto' \| 'xlarge' \| 'xxlarge'`
pinPosition	`false`	`boolean` If true, the overlay will attempt to prevent position shifting when sitting at the top of the anchor.
variant	`{ regular: 'anchored', narrow: 'anchored' }`	`{ regular?: 'anchored', narrow?: 'anchored' \| 'fullscreen' }` Optional prop to set variant for narrow screen sizes

Overlay