Component referenceVersion Draft
Popover
Popover anchors a small contextual surface to its trigger. Keep related controls together and group actions after their fields.
- Updated
Design notes
Radix manages positioning, dismissal and focus. Use Modal when the task needs a stronger interruption or more space.
Playground
Playgrounddemo.tsx
content/components/popover/demo.tsx
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667import { useState } from "react"
import { Button, Popover, PopoverClose, TextField } from "@yuzur1ha/ui"
import { DemoResult } from "../../examples/result"
export function PopoverDemo() {
const [open, setOpen] = useState(false)
const [name, setName] = useState("Alex Morgan")
const [draft, setDraft] = useState(name)
const [error, setError] = useState("")
return (
<>
<Popover
label="Edit profile"
className="demo-profile-popover"
open={open}
onOpenChange={(next) => {
setOpen(next)
if (next) {
setDraft(name)
setError("")
}
}}
trigger={<Button appearance="secondary">Edit display name</Button>}
>
<h2>Edit profile</h2>
<p>Choose the name shown on your profile.</p>
<form
className="popover-demo-form"
onSubmit={(event) => {
event.preventDefault()
const normalized = draft.trim()
if (normalized.length < 2) {
setError("Enter at least two non-space characters.")
return
}
setName(normalized)
setOpen(false)
}}
>
<TextField
label="Display name"
value={draft}
onChange={(event) => {
setDraft(event.target.value)
setError("")
}}
{...(error ? { error } : {})}
required
minLength={2}
maxLength={64}
/>
<div className="popover-demo-actions">
<PopoverClose asChild>
<Button appearance="text" size="small">
Cancel
</Button>
</PopoverClose>
<Button type="submit" size="small">
Apply
</Button>
</div>
</form>
</Popover>
<DemoResult>{name}</DemoResult>
</>
)
}
API
Popover
A portalled Radix popover anchored to one trigger element. Positioning, dismissal and focus callbacks apply to the content element.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
trigger | ReactElement | Yes | — | One ref-capable action element used as the popover trigger. |
label | string | Yes | — | Accessible name of the popover content. |
open | boolean | No | — | Controlled open state. Pair with onOpenChange. |
defaultOpen | boolean | No | — | Initial open state when open is omitted. |
onOpenChange | ((open: boolean) => void) | No | — | Called when opening or closing is requested. |
modal | boolean | No | false | Trap focus and disable outside interaction while open. |
showArrow | boolean | No | true | Render the decorative arrow pointing to the trigger. |
side | "left" | "right" | "bottom" | "top" | No | "bottom" | Preferred placement side; collision handling can choose another side. |
sideOffset | number | No | 8 | Gap in pixels between the trigger and content. |
align | "center" | "start" | "end" | No | "start" | Preferred alignment relative to the trigger. |
alignOffset | number | No | 0 | Pixel offset from the selected alignment. |
arrowPadding | number | No | 0 | Minimum distance in pixels between the arrow and the content corners. |
avoidCollisions | boolean | No | true | Adjust placement to keep content within the collision boundary. |
collisionBoundary | (Element | null) | (Element | null)[] | No | — | Element or elements used as the placement boundary; omitted uses the viewport. |
collisionPadding | number | Partial<Record<"left" | "right" | "bottom" | "top", number>> | No | 12 | Pixel padding inside the collision boundary, globally or per side. |
sticky | ("partial" | "always") | No | "partial" | Radix sticky-placement strategy: partial or always. |
hideWhenDetached | boolean | No | false | Hide content when its anchor is detached from the visible boundary. |
updatePositionStrategy | ("always" | "optimized") | No | "optimized" | Reposition with the optimized or always strategy. |
forceMount | true | No | — | Keep the Radix content mounted for externally managed visibility or animation. The consumer must manage its closed presentation. |
onEscapeKeyDown | ((event: KeyboardEvent) => void) | No | — | Called before Escape dismisses the surface; prevent default to keep it open. |
onPointerDownOutside | ((event: CustomEvent<{ originalEvent: PointerEvent; }>) => void) | No | — | Called for a pointer press outside the content; prevent default to cancel dismissal. |
onFocusOutside | ((event: CustomEvent<{ originalEvent: FocusEvent; }>) => void) | No | — | Called when focus moves outside the content; prevent default to cancel the associated outside interaction. |
onInteractOutside | ((event: CustomEvent<{ originalEvent: PointerEvent; }> | CustomEvent<{ originalEvent: FocusEvent; }>) => void) | No | — | Called for pointer or focus interaction outside the content; prevent default to cancel dismissal. |
onOpenAutoFocus | ((event: Event) => void) | No | — | Called before focus enters opened content; prevent default to choose the focus target. |
onCloseAutoFocus | ((event: Event) => void) | No | — | Called before focus returns after closing; prevent default when navigation manages focus. |
children | ReactNode | No | — | Content rendered inside the component. |
className | string | No | "" | Additional classes applied to the component’s documented root or control. |
id | string | No | — | DOM identifier for the rendered element. |
ref | Ref<HTMLDivElement> | No | — | Ref to the component’s documented DOM element. |
No custom imperative methods. Event callbacks are listed as properties.
PopoverClose
Closes the nearest matching overlay. Use asChild with one ref-capable action element, or render the default native button.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Render through one child element instead of the default element. The child must forward its ref and accept the supplied props. |
children | ReactNode | No | — | Content rendered inside the component. |
disabled | boolean | No | — | Disables the native control. |
onClick | MouseEventHandler<HTMLButtonElement> | No | — | Native activation handler. |
className | string | No | — | Additional classes applied to the component’s documented root or control. |
id | string | No | — | DOM identifier for the rendered element. |
ref | Ref<HTMLButtonElement> | No | — | Ref to the component’s documented DOM element. |
No custom imperative methods. Event callbacks are listed as properties.