Skip to content
Yuzur1ha Open

Component referenceVersion Draft

Popover

Popover anchors a small contextual surface to its trigger. Keep related controls together and group actions after their fields.

Design notes

Radix manages positioning, dismissal and focus. Use Modal when the task needs a stronger interruption or more space.

Playground

Playgrounddemo.tsx
Alex Morgan

content/components/popover/demo.tsx

import { 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.

PopoverProps
PropertyTypeRequiredDefaultDescription
triggerReactElementYes—One ref-capable action element used as the popover trigger.
labelstringYes—Accessible name of the popover content.
openbooleanNo—Controlled open state. Pair with onOpenChange.
defaultOpenbooleanNo—Initial open state when open is omitted.
onOpenChange((open: boolean) => void)No—Called when opening or closing is requested.
modalbooleanNofalseTrap focus and disable outside interaction while open.
showArrowbooleanNotrueRender the decorative arrow pointing to the trigger.
side"left" | "right" | "bottom" | "top"No"bottom"Preferred placement side; collision handling can choose another side.
sideOffsetnumberNo8Gap in pixels between the trigger and content.
align"center" | "start" | "end"No"start"Preferred alignment relative to the trigger.
alignOffsetnumberNo0Pixel offset from the selected alignment.
arrowPaddingnumberNo0Minimum distance in pixels between the arrow and the content corners.
avoidCollisionsbooleanNotrueAdjust 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.
collisionPaddingnumber | Partial<Record<"left" | "right" | "bottom" | "top", number>>No12Pixel padding inside the collision boundary, globally or per side.
sticky("partial" | "always")No"partial"Radix sticky-placement strategy: partial or always.
hideWhenDetachedbooleanNofalseHide content when its anchor is detached from the visible boundary.
updatePositionStrategy("always" | "optimized")No"optimized"Reposition with the optimized or always strategy.
forceMounttrueNo—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.
childrenReactNodeNo—Content rendered inside the component.
classNamestringNo""Additional classes applied to the component’s documented root or control.
idstringNo—DOM identifier for the rendered element.
refRef<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.

ComponentPropsWithRef<typeof PopoverClose>
PropertyTypeRequiredDefaultDescription
asChildbooleanNofalseRender through one child element instead of the default element. The child must forward its ref and accept the supplied props.
childrenReactNodeNo—Content rendered inside the component.
disabledbooleanNo—Disables the native control.
onClickMouseEventHandler<HTMLButtonElement>No—Native activation handler.
classNamestringNo—Additional classes applied to the component’s documented root or control.
idstringNo—DOM identifier for the rendered element.
refRef<HTMLButtonElement>No—Ref to the component’s documented DOM element.

No custom imperative methods. Event callbacks are listed as properties.