usePopover

Manages native HTML popover state in React. Built on the Popover API.

Usage

import { usePopover } from '@volvo-cars/react-headless';

const MyComponent = () => {
  const { popoverProps, togglePopover } = usePopover<HTMLDivElement>({
    behaviour: 'auto',
  });

  return (
    <div>
      <button onClick={togglePopover}>Open popover</button>
      <div className="popover p-24 m-24 shadow-sm" {...popoverProps}>
        Popover content
      </div>
    </div>
  );
};

Behaviour modes

The behaviour option controls how the popover behaves:

• auto (default) — closes when clicking outside or pressing Escape. Only one auto popover can be open at a time.
• manual — must be explicitly closed via hidePopover() or togglePopover().
• hint — similar to auto, but doesn’t close other popovers when opened. Useful for tooltips.

Handling toggle events

Use the onToggle callback to react to popover state changes:

import { usePopover } from '@volvo-cars/react-headless';

function Example() {
  const { popoverProps, togglePopover } = usePopover<HTMLDivElement>({
    onToggle: (event) => {
      if (event.newState === 'open') {
        console.log('Popover opened');
      } else {
        console.log('Popover closed');
      }
    },
  });

  return (
    <div>
      <button onClick={togglePopover}>Toggle</button>
      <div {...popoverProps}>Content</div>
    </div>
  );
}

API

Options

usePopover accepts an options object:

• behaviour — popover behaviour mode: 'auto' (default), 'manual', or 'hint'
• ref — optional ref to the popover element. If not provided, one will be created.
• onToggle — callback triggered on the popover ToggleEvent

Returns

• isOpen — whether the popover is currently open
• togglePopover — function to toggle the popover state
• showPopover — function to open the popover
• hidePopover — function to close the popover
• popoverProps — props to spread on the popover element