Overlays@knitui/components

Popover

Popover is a floating overlay anchored to a trigger element. Compose Popover.Target (the trigger) with Popover.Dropdown (the content panel). Supports uncontrolled and controlled open state, floating-ui placement, arrow, overlay scrim, focus trap, and ARIA roles.

WebiOSAndroidnative split3 style slots29 own props11 examples

Stories Source Tests Native source Open in Storybook

import { Popover } from "@knitui/components";

Playground

Loading playground…

positionPlacement of the dropdown relative to the target.

offsetGap between the target and dropdown as a space token or px number.

withArrowShow an arrow pointing at the target.

false

arrowSizeArrow edge length in px.

arrowOffset

arrowRadius

withOverlayRender a full-cover overlay scrim behind the open dropdown.

false

trapFocusTrap keyboard focus within the dropdown while open.

false

keepMountedKeep the dropdown mounted while closed (uses display:none).

false

closeOnClickOutside

true

closeOnEscape

true

disabledPrevent the dropdown from opening.

false

withRolesWire ARIA dialog roles between target and dropdown.

false

shadowDropdown shadow scale.

widthDropdown width; 'target' matches the trigger width.

Playground

<Popover
  position="bottom-start"
  offset="$xs"
  withArrow={false}
  withOverlay={false}
  trapFocus={false}
  keepMounted={false}
  closeOnClickOutside
  closeOnEscape
  disabled={false}
  withRoles={false}
  shadow="md"
/>

Examples

Controlled

Controlled open state — parent owns when the dropdown is visible.

Loading example…

ControlledSource Storybook

With Arrow

Arrow pointing at the target, shown at several placements.

Loading example…

With ArrowSource Storybook

Disabled

Disabled — the dropdown cannot open regardless of user interaction.

Loading example…

DisabledSource Storybook

With Overlay

Full-cover overlay scrim rendered behind the open dropdown.

Loading example…

With OverlaySource Storybook

With Roles

ARIA dialog roles wired between target and dropdown for assistive technology.

Loading example…

With RolesSource Storybook

Target Width

Dropdown width matches the trigger element width.

Loading example…

Target WidthSource Storybook

Shadows

The shadow prop lifts the dropdown off the page using the shared elevation ladder (xs → xl). Each popover below is always open and rendered inline (withinPortal={false}) inside its own relative wrapper so the dropdowns sit side by side without overlapping.

Loading example…

ShadowsSource Storybook

Styles

Per-slot styles targets individual parts — here the dropdown frame and the arrow.

Loading example…

StylesSource Storybook

Transitions

Configurable enter/exit animation via transitionProps. Pick a preset, then toggle the popover to watch it animate in and out (all driven by the shared Transition engine, so the same presets work on web and native).

Loading example…

TransitionsSource Storybook

Compound API

Compound API — Target + Dropdown composed inside a single Popover root.

Loading example…

Compound APISource Storybook

Props

Prop	Type	Default	Description
`animation`	`MotionPresetName \| undefined`	—	Motion preset for the dropdown — the unified `animation` vocabulary shared with Modal/Dialog/Drawer (e.g. `"fade"`, `"pop"`, `"scale"`). Sugar over `transitionProps.transition`, which wins if both are set.
`arrowOffset`	`PopoverAxisOffset \| undefined` $xxs · $xs · $sm · $md · $lg · $xl · $xxl · 4 · 5 · 8	`'$xxs'`	Arrow distance from the start/end edge when `arrowPosition="side"`.
`arrowPosition`	`ArrowPosition \| undefined`	`'side'`	Arrow alignment: centered, or pinned toward an aligned placement.
`arrowRadius`	`number \| undefined`	`0`	Corner radius of the arrow's outward corner in px.
`arrowSize`	`number \| undefined`	`7`	Arrow edge length in px.
`children`	`ReactNode`	—	Target + dropdown.
`closeOnClickOutside`	`boolean \| undefined`	`true`	Close the dropdown when a press lands outside it (web).
`closeOnEscape`	`boolean \| undefined`	`true`	Close the dropdown when the `Escape` key is pressed (web).
`defaultOpened`	`boolean \| undefined`	`false`	Uncontrolled initial opened state.
`disabled` system	`boolean \| undefined`	`false`	Prevent the dropdown from opening.
`keepMounted`	`boolean \| undefined`	`false`	Keep the dropdown mounted while closed (uses display:none).
`offset`	`PopoverOffset \| undefined` $xxs · $xs · $sm · $md · $lg · $xl · $xxl · 4 · 8 · 12	`'$xs'`	Gap between the target and dropdown as a space token or px number.
`onChange`	`((opened: boolean) => void) \| undefined`	—	Called when the opened state changes (open + close).
`onClose`	`(() => void) \| undefined`	—	Called when the dropdown closes.
`onDismiss`	`(() => void) \| undefined`	—	Called when the dropdown is dismissed by an outside-press or `Escape` — distinct from `onClose`, which fires on every close (including programmatic / controlled ones).
`onOpen`	`(() => void) \| undefined`	—	Called when the dropdown opens.
`onPositionChange`	`((position: PopoverPosition) => void) \| undefined`	—	Called with the RESOLVED placement whenever it changes (e.g. on flip/shift).
`opened`	`boolean \| undefined`	—	Controlled opened state.
`overlayProps`	`Partial<OverlayProps> \| undefined`	—
`position`	`Placement \| undefined` top · top-start · top-end · bottom · bottom-start · bottom-end · left · left-start · left-end · right · right-start · right-end	`'bottom-start'`	Placement of the dropdown relative to the target.
`radius` system	`RadiusTokens \| undefined`	—	Dropdown border radius.
`returnFocus`	`boolean \| undefined`	`false`	Return focus to the target when the dropdown closes (web).
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` xs · sm · md · lg · xl	`'md'`	Dropdown shadow scale.
`strategy`	`Strategy \| undefined`	`'fixed'`	Positioning strategy.
`styles` system	`SlotStyles<PopoverStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching styled part.
`transitionProps`	`OverlayTransitionConfig \| undefined`	`{ transition: 'fade', duration: 150, timingFunction: 'ease-in-out' }`	Enter/exit animation: { transition, duration, exitDuration, timingFunction }. Defaults to a 150ms fade.
`trapFocus`	`boolean \| undefined`	`false`	Trap keyboard focus within the dropdown while open.
`width`	`PopoverWidth \| undefined` max-content · target · 200 · 300	`'max-content'`	Dropdown width; 'target' matches the trigger width.
`withArrow`	`boolean \| undefined`	`false`	Show an arrow pointing at the target.
`withinPortal`	`boolean \| undefined`	`true`	Render the dropdown in a portal.
`withOverlay`	`boolean \| undefined`	`false`	Render a full-cover overlay scrim behind the open dropdown.
`withRoles`	`boolean \| undefined`	`false`	Wire ARIA dialog roles between target and dropdown.
`zIndex`	`number \| undefined`	`300`	Dropdown `z-index`.

Style slots

Every part of Popover can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`arrow`	`styles={{ arrow: { … } }}`
`dropdown`	`styles={{ dropdown: { … } }}`
`overlay`	`styles={{ overlay: { … } }}`