Popover

Anchor floating content, like those found in iOS, to a trigger element in one of four directions.

Examples

<Popover> wraps a trigger element as children and shows content (and an optional title) anchored to it on click. It opens and closes itself; see Controlling the popover to drive it from outside.

import { Popover, Button } from '@chassis-ui/react'

export const Example = () => {
  return (
    <Popover
      title="Popover title"
      content="And here's some amazing content. It's very engaging. Right?"
      placement="right"
    >
      <Button color="danger" size="lg">
        Click to toggle popover
      </Button>
    </Popover>
  )
}

Four directions

Four options are available: top, right, bottom, and left aligned. Directions are mirrored when using Chassis in RTL.

import { Popover, Button } from '@chassis-ui/react'

export const Example = () => {
  return (
    <>
      <Popover content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus." placement="top">
        <Button color="secondary">Popover on top</Button>
      </Popover>
      <Popover
        content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
        placement="right"
      >
        <Button color="secondary">Popover on right</Button>
      </Popover>
      <Popover
        content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus."
        placement="bottom"
      >
        <Button color="secondary">Popover on bottom</Button>
      </Popover>
      <Popover content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus." placement="left">
        <Button color="secondary">Popover on left</Button>
      </Popover>
    </>
  )
}

Pass visible with onVisibleChange to hold the open state yourself. The popover then shows and hides only when visible changes: a click on the trigger, a press outside and the Escape key are reported to onVisibleChange with the state they ask for, and nothing happens until you set it. A state setter fits as it is.

Popover is closed.

import { useState } from 'react'
import { Button, Popover } from '@chassis-ui/react'

export const Example = () => {
  const [visible, setVisible] = useState(false)

  return (
    <div className="d-flex align-items-center gap-sm">
      <Popover
        title="Saved filters"
        content={
          <Button size="sm" onClick={() => setVisible(false)}>
            Apply and close
          </Button>
        }
        placement="bottom"
        visible={visible}
        onVisibleChange={setVisible}
      >
        <Button color="secondary">Filters</Button>
      </Popover>
      <span className="form-help">Popover is {visible ? 'open' : 'closed'}.</span>
    </div>
  )
}

defaultVisible opens the popover on first render and leaves it uncontrolled. onShow and onHide report that the popover has shown or hidden; they don't carry the state, so use onVisibleChange to control it.

The panel

Every other attribute goes to the panel, the .popover element: className, style, id, data-* attributes and event handlers. A ref on <Popover> points to the panel too, and is null while the popover is closed. The trigger keeps its own props and ref.

API

Prop	Type	Default
`children`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—
The trigger: a single element, which opens the popover on click.
`content`	`ReactNode`	—
Content node for your component.
`defaultVisible?`	`boolean`	—
Whether the popover is open when it first renders. Use it instead of `visible` when nothing outside needs to control the popover.
`offset?`	`[number, number]`	`[0, 8]`
Offset of the popover relative to its target, as `[crossAxis, mainAxis]`.
`onHide?`	`(() => void)`	—
Callback fired when the popover hides.
`onShow?`	`(() => void)`	—
Callback fired when the popover shows.
`onVisibleChange?`	`((visible: boolean) => void)`	—
Callback fired when the popover asks to show or hide: a click on the trigger, a click outside, the Escape key, or the closing of the dialog it is in. Receives the state it asks for. With `visible` set, the popover changes only when `visible` does.
`placement?`	`Placement`	`right`
Describes the preferred placement of your component. Chassis will flip it to keep it in view.
`title?`	`ReactNode`	—
Title node for your component.
`visible?`	`boolean`	—
Whether the popover is open. Setting it makes the popover controlled: it shows and hides only when this changes, so pair it with `onVisibleChange`. Leave it unset, or use `defaultVisible`, for a popover that opens and closes itself.