Bridge UI

Popover

Anchored, non-modal floating panel for free-form content.

Introduction

Popovers show free-form content—filters, short forms, profile cards—in a panel anchored to a trigger. They are non-modal: the page stays interactive, there is no focus trap, and the body does not scroll-lock by default.

Popover vs Menu vs Tooltip: Use Menu for a list of actions, where arrow keys move between items. Use Tooltip for short hover text. Use Popover when the panel holds fields or richer content: Tab moves through its controls and arrow / Home / End keys stay inside inputs.

Import

import { Popover } from "@bridge-ui/vue/Components/Popover";
import { Popover } from "@bridge-ui/react/Components/Popover";

Basic usage

Provide the opener via the trigger slot (Vue) or slots.trigger (React) and control visibility with v-model / show + onShowChange. The title renders a heading at the top of the panel and labels the dialog.

Form with ActionFooter

Close the popover from its content: the Vue default slot receives close, and in React pass a function as children to receive it. Pair it with ActionFooter for a Cancel / Apply row.

Arrow and placement

Set arrow to point at the anchor and placement to position the panel. The default placement is bottom-start; this example uses top.

Custom title

Pass rich content as the heading: a ReactNode to title in React, or the title slot in Vue (the slot wins over the prop). It still labels the dialog.

Without a title

When there is no visible heading, label the dialog with aria-label through customProps.content.

Persistent

When persistent is true, Escape, click-away, and focus leaving do not close the popover. Close it from the content.

External anchor

Pass anchorEl to position against an element outside the popover instead of using the trigger slot. It is also used for click-away, so put the button that toggles the popover inside the anchor element: pressing it again then closes the popover instead of closing and reopening it.

Without a trigger slot no root element renders, so extra attributes are not applied: use classes.content / customProps.content to style or tag the panel.

Inside a Menu

A Popover (or Menu) opened from inside a Menu keeps that menu open when its opener is inside the menu panel: the trigger slot, or anchorEl when there is no trigger. Otherwise, opening a popover closes any open menu.

Customization

Fine-tune closing with closeOnEscape, closeOnClickAway, and closeOnFocusOut. Style the panel with rounded, shadow, and the classes prop to target individual parts (root, trigger, content, title, arrow). Popover shares the Menu panel radius and shadow scales; set app-wide defaults through components.Popover.defaultProps.

Menu, Tooltip, Modal, Button

Accessibility

  • The panel has role="dialog" (non-modal: no focus trap, no scroll lock by default). The trigger wrapper gets aria-haspopup="dialog", aria-expanded, and aria-controls.
  • Label the dialog with title (aria-labelledby) or, without one, aria-label via customProps.content.
  • On open, focus moves to the first focusable element (or the panel itself) unless disableAutoFocus is set.
  • Escape closes the top-most layer. Closing while focus is inside the panel (Escape or close) returns focus to the trigger; a click outside leaves focus where the pointer put it.
  • Clicks inside layers opened from the content (a Select list, a nested Menu) do not close the popover.
  • Pass teleportTo={false} to render in place and keep the natural Tab order after the trigger.

Anatomy

<div> <!-- Popover root -->
  <div> <!-- trigger wrapper (aria-haspopup="dialog") -->
    <button> <!-- trigger slot -->
  </div>
  <div role="dialog"> <!-- portaled content -->
    <div> <!-- title -->
    <!-- content -->
    <div> <!-- arrow (when arrow is set) -->
  </div>
</div>

The content is portaled to teleportTo (default "body") and positioned relative to the trigger or anchorEl.

API

Prop Type Default Description
@close — — Emitted when the user dismisses (Escape, click-away, or focus leaving) or content calls close. Not emitted when the parent sets v-model to false directly.
@show-change (show: boolean) => void — Equivalent to onShowChange when you prefer events over a callback prop.
anchorEl HTMLElement | null — External anchor for positioning and click-away, used instead of the trigger slot wrapper.
title string — Heading at the top of the panel; labels the dialog. The title slot wins.
v-model boolean false Whether the popover is open.
Slot Props Description
default { close: () => void } The popover content.
title — Custom heading content (labels the dialog).
trigger — The element that opens the popover.
Prop Type Default Description
anchorEl HTMLElement | RefObject<HTMLElement | null> | null — External anchor for positioning and click-away, used instead of the slots.trigger wrapper.
children ReactNode | ((props: PopoverRenderProps) => ReactNode) — The popover content. Pass a function to receive close.
onClose () => void — Called when the user dismisses (Escape, click-away, or focus leaving) or content calls close. Not fired when the parent sets show={false} directly.
onShowChange (show: boolean) => void — Called when show should change.
show boolean false Whether the popover is open. Use with onShowChange for controlled state.
slots PopoverSlots — trigger: the element that opens the popover.
title ReactNode — Heading at the top of the panel; labels the dialog.
Prop Type Default Description
arrow boolean false Whether to show an arrow pointing at the anchor.
classes PopoverClasses — Part classes: root, trigger, content, title, arrow.
closeOnClickAway boolean true Whether the popover closes when clicking outside the trigger and content.
closeOnEscape boolean true Whether the popover closes on Escape.
closeOnFocusOut boolean true Whether the popover closes when focus moves outside the trigger and content.
customProps PopoverCustomProps — Props forwarded to each part (root, trigger, content, title, arrow).
disableAutoFocus boolean false When true, the popover does not move focus into the content on open.
disableScrollLock boolean true When true, body scroll is not locked while the popover is open.
keepMounted boolean false When true, the popover stays mounted after closing (hidden).
matchWidth boolean false When true, the content width matches the trigger / anchor.
offset number 8 Gap between the anchor and the content (px).
persistent boolean false When true, Escape, click-away, and focus leaving do not close the popover.
placement PositionPlacement "bottom-start" Preferred placement of the content relative to the anchor.
rounded PopoverRounded "md" Border radius of the content.
shadow PopoverShadow "md" Shadow applied to the content.
strategy PositionStrategy "fixed" CSS position strategy for the content.
teleportTo string | false "body" Portal target. Pass false to render in place (keeps the natural Tab order after the trigger).