edbnedbn/ui
ComponentsMapsAudioPDF
GitHub stars
Explorer
Get Started
Components

Popover

Floating popover with auto-positioning and focus management.

Componentsdocsbase-ui/popover↗

Installation

pnpm dlx edbn-ui@latest add popover

Manual

1

Create a file and paste the following code into it.

API Reference

Root

Groups all parts of the popover. Doesn't render its own HTML element.

defaultOpenboolean
=false

Initial open state

openboolean

Controlled open state

onOpenChange(open: boolean, details) => void

Called when state changes

onOpenChangeComplete(open: boolean) => void

Called after animation completes

actionsRefRefObject<Popover.Root.Actions | null>

Imperative close and unmount actions

modalboolean | 'trap-focus'
=false

Limit outside interaction or trap focus when open

handlePopover.Handle<Payload>

Handle for detached triggers

defaultTriggerIdstring | null

Initial associated trigger id

triggerIdstring | null

Controlled associated trigger id

childrenReactNode | PayloadChildRenderFunction<Payload>

Popover content or payload-aware render child

Trigger

A button that opens the popover. Renders a button element.

handlePopover.Handle<Payload>

Associates this trigger with a detached root

payloadPayload

Payload passed to a render-child root

idstring

Element and active trigger id

openOnHoverboolean
=false

Open on hover as well as press/focus

delaynumber
=300

Delay before hover open in milliseconds

closeDelaynumber
=0

Delay before closing a hover-opened popover

nativeButtonboolean
=true

Render as native button

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Trigger data attributes
AttributeDescription
data-popup-openPresent when popover is open
data-pressedPresent when the trigger is pressed

Portal

Moves the popup to a different part of the DOM. Renders a div element.

containerHTMLElement | ShadowRoot | RefObject | null

Portal container

keepMountedboolean
=false

Keep in DOM when closed

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Backdrop

An overlay displayed beneath the popover. Renders a div element.

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Backdrop data attributes
AttributeDescription
data-openPresent when popover is open
data-closedPresent when popover is closed
data-starting-stylePresent when animating in
data-ending-stylePresent when animating out

Positioner

Positions the popup against the trigger. Renders a div element.

sideSide
='bottom'

Side relative to anchor

sideOffsetnumber
=0

Distance from anchor

alignOffsetnumber | OffsetFunction
=0

Offset along the alignment axis

arrowPaddingnumber
=5

Minimum arrow distance from popup edges

anchorElement | VirtualElement | RefObject | function | null

Custom positioning anchor

collisionAvoidanceCollisionAvoidance

Flip, shift, or disable collision handling

collisionBoundaryBoundary
='clipping-ancestors'

Boundary used for collision detection

collisionPaddingPadding
=5

Space from the collision boundary

stickyboolean
=false

Keep visible after the anchor scrolls away

positionMethod'absolute' | 'fixed'
='absolute'

CSS positioning strategy

align'start' | 'center' | 'end'
='center'

Alignment relative to side

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Positioner data attributes
AttributeDescription
data-openPresent when popup is open
data-closedPresent when popup is closed
data-anchor-hiddenPresent when the anchor is hidden
data-sideSide popup is positioned on
data-alignAlignment relative to side
Positioner CSS variables
VariableDescription
--anchor-heightAnchor height
--anchor-widthAnchor width
--available-heightAvailable height between anchor and viewport edge
--available-widthAvailable width between anchor and viewport edge
--positioner-heightCurrent positioner height for size animations
--positioner-widthCurrent positioner width for size animations
--transform-originTransform origin for anchored animations

Popup

A container for the popover contents. Renders a div element.

initialFocusboolean | RefObject<HTMLElement> | function

Element to focus on open

finalFocusboolean | RefObject<HTMLElement> | function

Element to focus on close

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Popup data attributes
AttributeDescription
data-openPresent when popover is open
data-closedPresent when popover is closed
data-alignAlignment relative to side
data-instantPresent when animations should be skipped
data-sideSide popup is positioned on
data-starting-stylePresent when animating in
data-ending-stylePresent when animating out
Popup CSS variables
VariableDescription
--popup-heightCurrent popup height
--popup-widthCurrent popup width

Arrow

Displays an arrow element positioned against the anchor. Renders a div element.

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Arrow data attributes
AttributeDescription
data-openPresent when popover is open
data-closedPresent when popover is closed
data-uncenteredPresent when the arrow cannot be centered
data-alignAlignment relative to side
data-sideSide popup is positioned on

Title

An accessible title for the popover. Renders an h2 element.

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Description

An accessible description for the popover. Renders a p element.

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Close

A button that closes the popover. Renders a button element.

nativeButtonboolean
=true

Render as native button

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

CloseIconButton

EDBN styled corner close button built on Popover.Close with an icon and accessible label.

aria-labelstring
='Close popover'

Accessible label for the icon button

nativeButtonboolean
=true

Render as native button

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Viewport

A viewport for animating content transitions between trigger payloads. Renders a div element.

childrenReactNode

Content to render inside the transition container

classNamestring | function

CSS class name

styleCSSProperties | function

Inline style or state-based style function

renderReactElement | function

Custom render function

Viewport data attributes
AttributeDescription
data-activation-directionDirection from the previous trigger to the new trigger
data-currentApplied to the current content container
data-instantPresent when animations should be skipped
data-previousApplied to the exiting content container
data-transitioningPresent while content is transitioning
Viewport CSS variables
VariableDescription
--popup-heightParent popup height for transition containers
--popup-widthParent popup width for transition containers

Handle

Base UI handle utility for detached triggers and imperative popover control.

isOpenboolean
=readonly

Whether the associated popover is open

open(triggerId: string) => void
=method

Open and associate the popover with a trigger id

close() => void
=method

Close the associated popover

createHandle

Function exported as createPopoverHandle for creating typed detached-trigger handles.

returnPopover.Handle<Payload>

A new imperative popover handle