XiodUI
HomeDocs
OverviewComponentsStyling & CustomizationChangelog

Components

  • Accordion
  • Agent Steps
  • Alert
  • Alert Dialog
  • Aspect Ratio
  • Autocomplete
  • Avatar
  • Badge
  • Breadcrumb
  • Button
  • Button Group
  • Button Split
  • Calendar
  • Card
  • Carousel
  • Checkbox
  • Circular Progress
  • Collapsible
  • Color Picker
  • Combobox
  • Command
  • Context Menu
  • Copy To Clipboard
  • Corner Badge
  • Dashboard Grid
  • Date Picker
  • Dialog
  • Dot Matrix
  • Draggable
    Updated
  • Drawer
  • Empty
  • Field
  • Fieldset
  • File Upload
    Updated
  • Form
  • Frame
  • Gauge
  • Grid
  • Group
  • Input
  • Input Group
  • Input OTP
  • Input Payment
  • Input Phone
    Updated
  • Input Sensitive
  • Kbd
  • Kinetic Click
  • Label
  • List Box
    Updated
  • Loader
  • Marker
  • Menu
  • Menubar
  • Message
  • Meter
  • Morphic Toast
  • Navigation Menu
  • Number Field
  • Option Picker
  • Orb
  • Pagination
  • Popover
  • Preview Card
    Updated
  • Progress
  • Radio
  • Resizable
  • Ruler Picker
  • Scroll Area
  • Scroll Bar
  • Select
  • Separator
  • Sidebar
  • Skeleton
  • Slider
  • Sortable
  • Switch
  • Table
  • Tabs
  • Text
  • Textarea
  • Timeline
  • Toast
  • Toggle
  • Toggle Group
  • Toolbar
  • Tooltip
  • Waveform
  • Wheel Picker

Loading...

Preview Skeleton

Installation Skeleton

Usage Skeleton

API Reference Skeleton

Sponsors

Support the development of XiodUI and help us build the best component library on Earth.

+++
Sponsor on GitHub

Popover

Previous: PaginationNext: Preview Card

A floating panel of content, opened from a button.

Preview

Loading Preview...

Installation

bun add xiod-ui

Usage

Imports

1import {2  Popover,3  PopoverArrow,4  PopoverClose,5  PopoverDescription,6  PopoverPopup,7  PopoverTitle,8  PopoverTrigger,9  PopoverCreateHandle10} from "xiod-ui/popover";

Anatomy

1<Popover>2  <PopoverTrigger />3  <PopoverPopup>4    <PopoverTitle />5    <PopoverDescription />6  </PopoverPopup>7</Popover>

API Reference

Detailed documentation of properties and options.

Popover

PropTypeDefaultDescription
actionsRef
RefObject<PopoverRootActions | null>
–

A ref to imperative actions.

  • unmount: Ends the closing phase of the popover after an externally controlled closing animation finishes.

Call preventUnmountOnClose() in onOpenChange first, otherwise the popover completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.

  • close: Closes the popover imperatively when called.
PaginationPreview Card
children
ReactNode | PayloadChildRenderFunction<Payload>
–

The content of the popover. This can be a regular React node or a render function that receives the payload of the active trigger.

defaultOpen
boolean
false

Whether the popover is initially open.

To render a controlled popover, use the open prop instead.

defaultTriggerId
string|null
–

ID of the trigger that the popover is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open popover.

handle
PopoverHandle<Payload>
–

A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state.

modal
boolean|"trap-focus"
false

Determines if the popover enters a modal state when open.

  • true: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.
  • false: user interaction with the rest of the document is allowed.
  • 'trap-focus': focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.

On touch devices, a true modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.

When modal is true, focus trapping is enabled only if <Popover.Close> is rendered inside <Popover.Popup>. It can be visually hidden with your own CSS if needed, such as Tailwind's sr-only utility.

When modal is 'trap-focus', render <Popover.Close> inside <Popover.Popup> so touch screen readers can escape the popup.

onOpenChange
((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)
–

Event handler called when the popover is opened or closed.

onOpenChangeComplete
((open: boolean) => void)
–

Event handler called after any animations complete when the popover is opened or closed.

open
boolean
–

Whether the popover is currently open.

triggerId
string|null
–

ID of the trigger that the popover is associated with. This is useful in conjunction with the open prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the open prop is not set).

PopoverArrow

Accepts className, style and render, plus every native attribute of the element it renders.

PopoverClose

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
nativeButton
boolean
true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

PopoverDescription

Accepts className, style and render, plus every native attribute of the element it renders.

PopoverPopup

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
align
"center"|"start"|"end"
center

How the calendar lines up with the trigger along that side.

alignOffset
number|OffsetFunction
0

Additional offset along the alignment axis, in pixels.

anchor
Popover$1.Positioner.Props["anchor"]
–

An element to position the popup against. Defaults to the trigger.

collisionAvoidance
CollisionAvoidance
–

How the popup avoids collisions with the edges of the viewport.

finalFocus
boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)
–

Determines the element to focus when the popover is closed.

  • false: Do not move focus.
  • true: Move focus based on the default behavior (trigger or previously focused element).
  • RefObject: Move focus to the ref element.
  • function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.
hideArrow
boolean
false

Whether to hide the arrow that points at the trigger.

initialFocus
boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)
–

Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.

  • false: Do not move focus.
  • true: Move focus based on the default behavior (first tabbable element or popup).
  • RefObject: Move focus to the ref element.
  • function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false
side
"top"|"bottom"|"left"|"right"|"inline-end"|"inline-start"
bottom

Which side of the copy button the tooltip and toast open on.

sideOffset
number|OffsetFunction
8

The gap between the trigger and the calendar, in pixels.

tooltipStyle
boolean
false

Whether the popup uses the compact look of a tooltip: smaller text, tighter padding and a width that fits the content.

PopoverTitle

Accepts className, style and render, plus every native attribute of the element it renders.

PopoverTrigger

Accepts className, style and render, plus every native attribute of the element it renders.

PropTypeDefaultDescription
closeDelay
number
0

How long to wait before closing the popover that was opened on hover. Specified in milliseconds.

Requires the openOnHover prop.

delay
number
300

How long to wait before the popover may be opened on hover. Specified in milliseconds.

Requires the openOnHover prop.

handle
PopoverHandle<unknown>
–

A handle to associate the trigger with a popover.

id
string
–

ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot triggerId prop).

nativeButton
boolean
true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>). Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).

openOnHover
boolean
false

Whether the popover should also open when the trigger is hovered.

payload
unknown
–

A payload to pass to the popover when it is opened.

Helpers

PopoverCreateHandle is called, not rendered. It creates a handle: pass it as handle to a trigger and to the root, and the trigger can sit anywhere in the tree, outside the root.

/
undefined
to do nothing.