Popover

A small panel that opens next to a button, with content the user can interact with.

Usage

Code
import { Popover } from '@leverui/components';
Code
<Popover.Root>
  <Popover.Trigger />
  <Popover.Positioner>
    <Popover.Content>
      <Popover.CloseTrigger />
      <Popover.Arrow>
        <Popover.ArrowTip />
      </Popover.Arrow>
      <Popover.Body>
        <Popover.Title />
      </Popover.Body>
    </Popover.Content>
  </Popover.Positioner>
</Popover.Root>

Shortcuts

Arrow

Popover.Arrow renders Popover.ArrowTip inside itself by default.

Code
<Popover.Arrow>
  <Popover.ArrowTip />
</Popover.Arrow>
Code
<Popover.Arrow />

Examples

Controlled

Use the open and onOpenChange to control the visibility of the popover.

Multiple Triggers

Don't mount a popover per button. Put value on each Trigger under one Root. Click another trigger and the same popover moves to it.

Track the active trigger with triggerValue and onTriggerValueChange on Root. If the target is not a button, use positioning.getAnchorRect.

Sizes

Use the size prop to change the size of the popover component.

Lazy Mount

Use the lazyMount and/or unmountOnExit prop to defer the mounting of the popover content until it's opened.

Placement

Use the positioning.placement prop to configure the underlying floating-ui positioning logic.

Offset

Use the positioning.offset prop to adjust the position of the popover content.

Same Width

Use the positioning.sameWidth prop to make the popover content the same width as the trigger.

Nested Popover

When nesting floating elements like popover, select, menu, inside of the popover, avoid portalling them to the document's body.

Code
-<Portal>
  <Popover.Positioner>
    <Popover.Content>
      {/* ... */}
    </Popover.Content>
  </Popover.Positioner>
-</Portal>

Initial Focus

Use the initialFocusEl prop to set the initial focus of the popover content.

Form

Here's an example of a popover with a form inside.

Custom Background

Use the --leverui-popover-background CSS variable to change the background color of the popover content and its arrow.

Open From Dialog

To use the Popover within a Dialog, you need to avoid portalling the Popover.Positioner to the document's body.

Code
-<Portal>
  <Popover.Positioner>
    <Popover.Content>
      {/* ... */}
    </Popover.Content>
  </Popover.Positioner>
-</Portal>

If you have set scrollBehavior="inside" on the Dialog, you need to:

  • Set the popover positioning to fixed to avoid the popover from being clipped by the dialog.
  • Set hideWhenDetached to true to hide the popover when the trigger is scrolled out of view.
Code
<Popover.Root positioning={{ strategy: 'fixed', hideWhenDetached: true }}>{/* ... */}</Popover.Root>

Guide

Accessing popover context

usePopoverContext reads the popover's state and methods from any component inside it. It returns an accessor, so call it to get the current value.

Code
import { Popover, usePopoverContext } from '@leverui/components';
function PopoverStatus() {
  const popover = usePopoverContext();
  return <div>Popover is {popover().open ? 'open' : 'closed'}</div>;
}

const MyPopover = () => (
  <Popover.Root>
    <Popover.Trigger>Open</Popover.Trigger>
    <Popover.Positioner>
      <Popover.Content>
        <PopoverStatus />
      </Popover.Content>
    </Popover.Positioner>
  </Popover.Root>
);

Closing programmatically

Call setOpen(false) on the context.

Code
import { Button, Popover, usePopoverContext } from '@leverui/components';
function CloseButton() {
  const popover = usePopoverContext();
  return <Button onClick={() => popover().setOpen(false)}>Close Popover</Button>;
}

const MyPopover = () => (
  <Popover.Root>
    <Popover.Trigger>Open</Popover.Trigger>
    <Popover.Positioner>
      <Popover.Content>
        <CloseButton />
      </Popover.Content>
    </Popover.Positioner>
  </Popover.Root>
);

Positioning based on ref

Return another element's position from positioning.getAnchorRect().

Code
import { Popover } from '@leverui/components';
function MyPopover() {
  let anchor: HTMLDivElement | undefined;
  return (
    <>
      <div ref={anchor}>Anchor Element</div>
      <Popover.Root
        positioning={{
          getAnchorRect() {
            return anchor?.getBoundingClientRect() ?? null;
          },
        }}
      >
        <Popover.Trigger>Open</Popover.Trigger>
        <Popover.Positioner>
          <Popover.Content>
            <Popover.Body>This popover is anchored to the div above</Popover.Body>
          </Popover.Content>
        </Popover.Positioner>
      </Popover.Root>
    </>
  );
}

Props

Root

PropDefaultTypeDescription
autoFocustruebooleanFocus the first focusable element on open.
closeOnEscapetruebooleanClose on Escape.
closeOnInteractOutsidetruebooleanClose on a click outside.
restoreFocustruebooleanReturn focus to where it was before opening.
size'md''xs' | 'sm' | 'md' | 'lg'Popover size.
unstyled—booleanTurn off the Lever UI styles.
defaultOpen—booleanOpen on first render. Uncontrolled.
defaultTriggerValue—stringTrigger value on first render. Uncontrolled.
finalFocusEl—() => MaybeElementElement focused on close.
id—stringUnique id.
ids—Element ID mapIds for the popover's parts.
immediate—booleanApply present changes now, not next frame.
initialFocusEl—() => HTMLElement | nullElement focused on open.
lazyMountfalsebooleanRender the content on first open.
modalfalsebooleanBlock outside interaction and scrolling, hide the page from screen readers, keep focus inside.
onEscapeKeyDown—(event: KeyboardEvent) => voidCalled when Escape is pressed.
onExitComplete—VoidFunctionCalled when the closing animation ends.
onFocusOutside—(event: FocusOutsideEvent) => voidCalled when focus moves outside.
onInteractOutside—(event: InteractOutsideEvent) => voidCalled on interaction outside.
onOpenChange—(details: OpenChangeDetails) => voidCalled when the popover opens or closes.
onPointerDownOutside—(event: PointerDownOutsideEvent) => voidCalled on pointer down outside.
onRequestDismiss—(event: LayerDismissEvent) => voidCalled when this layer closes because a parent layer closed.
onTriggerValueChange—(details: TriggerValueChangeDetails) => voidCalled when the trigger value changes.
open—booleanControlled open state.
persistentElements—(() => Element | null)[]Elements that keep pointer events and do not close the popover.
positioning—PositioningOptionsPositioning options for the content.
present—booleanControlled presence of the content.
skipAnimationOnMountfalsebooleanSkip the animation on first appearance.
translations—IntlTranslationsTranslated screen reader text for parts and states.
triggerValue—stringControlled trigger value.
unmountOnExitfalsebooleanRemove the content from the page on close.

Trigger

PropDefaultTypeDescription
asbuttonNative HTML tagHTML tag to render.
asChild—Solid render functionRender your own element with the trigger's props.
value—stringIdentifies this trigger.

Title names the panel and Description explains it. Keep portaled content inside the theme scope it needs. Use Dialog for modal work.

Customize with CSS

Load the package stylesheet first. Set class or style on any part, or override the variables on Popover.Content.

Code
.account-popover {
  --leverui-popover-background: #f5f8ff;
  --leverui-popover-size: 24rem;
  --leverui-popover-padding: 1.25rem;
}

The arrow takes the content's background. size is responsive. unstyled turns off the default styles but keeps focus and closing behavior.

Explorer

Click a part name in the sidebar to highlight it in the preview.

Component Anatomy

Hover to highlight, click to select parts