Popover | Tuff Docs

Usage

Basic

Loading demo...

Trigger and Panel

trigger picks click or hover; panelBackground and the other panel* props style the panel.

Loading demo...

Tabs hold the top-level sections; light actions go in TxDropdownMenu, short notes in TxPopover, and dense settings in TxDrawer.

Loading demo...

Best Practices

Hold short notes, compact filters, and one or two light actions; move anything past one screen or with many fields to a Drawer.
Set toggleOnReferenceClick=false when the reference contains an input or manages its own focus, as TxSearchSelect does.
Keep keepAliveContent on for stateful filters and small forms; static copy can turn it off.
Bound option panels with maxHeight or inner scrolling rather than letting a popover cover the viewport.
Turn on showArrow only when triggers sit close together and the panel must show which one it belongs to.

API Reference

Props

Prop	Type	Default	Description
`modelValue`	`boolean`	-	Whether the panel is open (`v-model`); omit it for uncontrolled use.
`disabled`	`boolean`	`false`	Blocks opening and closes an open panel.
`eager`	`boolean`	`false`	Mounts the content before the first open.
`placement`	`PopoverPlacement`	`'bottom-start'`	Preferred side.
`offset`	`number`	auto	Gap to the reference: `6` without an arrow, `max(8, arrowSize / 2 + 2)` with one.
`width`	`number`	`0`	Panel width; `0` matches the reference width.
`minWidth`	`number`	`0`	Minimum width.
`maxWidth`	`number`	`360`	Maximum width.
`maxHeight`	`number`	`420`	Maximum height; content beyond it scrolls inside the panel.
`unlimitedHeight`	`boolean`	`false`	Removes the height cap, for panels that scroll themselves.
`referenceFullWidth`	`boolean`	`false`	Stretches the reference container to full width.
`referenceClass`	`BaseAnchorClassValue`	-	Extra class for the reference wrapper.
`showArrow`	`boolean`	`false`	Shows an arrow.
`arrowSize`	`number`	`12`	Arrow size in px.
`trigger`	`'click' \| 'hover' \| 'manual'`	`'click'`	How it opens; `manual` binds no reference interaction, so `modelValue` alone decides.
`openDelay`	`number`	From the `menu` preset (`120`)	Hover open delay in ms; the shared delay service supplies it when unset.
`closeDelay`	`number`	From the `menu` preset (`100`)	Hover close delay in ms; the shared delay service supplies it when unset.
`animation`	`BaseAnchorAnimationOptions`	`{ type: 'expand' }`	Animation config forwarded to BaseAnchor; each type uses its own default timing.
`virtualReference`	`BaseAnchorVirtualReference`	-	Positions against an arbitrary rect, such as the pointer or a selection, instead of the reference.
`matchReferenceWidth`	`boolean`	`width <= 0`	With `width` at `0`, matches the reference width; `false` sizes the panel to its content.
`keepAliveContent`	`boolean`	`true`	Keeps content and its state after close.
`toggleOnReferenceClick`	`boolean`	`trigger === 'click'`	Toggles on reference click.
`panelVariant`	`'solid' \| 'dashed' \| 'plain'`	`'solid'`	Panel border style.
`panelBackground`	`'pure' \| 'mask' \| 'blur' \| 'glass' \| 'refraction'`	`'refraction'`	Panel background.
`panelShadow`	`'none' \| 'soft' \| 'medium'`	`'soft'`	Panel shadow.
`panelRadius`	`number`	`18`	Panel corner radius in px.
`panelPadding`	`number`	`10`	Panel padding in px.
`panelCard`	`BaseAnchorPanelCardProps`	-	Advanced overrides forwarded to the panel card.
`closeOnClickOutside`	`boolean`	`true`	Closes on an outside click; ignored with `hover`.
`closeOnEsc`	`boolean`	`true`	Closes on Escape.

Events

Event	Params	Description
`open`	-	Fires when the popover opens itself.
`close`	-	Fires when the popover closes itself.
`update:modelValue`	`boolean`	Fires when the popover requests an open-state change, controlled or not.

Slots

Slot	Props	Description
`reference`	-	Trigger content, rendered inside the reference wrapper.
`default`	`{ side: string }`	Panel content; `side` is the final side.

Exposed Methods

Name	Type	Description
`updatePosition`	`() => void`	Recomputes the position; call it after the `virtualReference` rect changes.

Overview

With modelValue it is controlled; otherwise it keeps its own open state.
With trigger="click", a reference click toggles it and an outside click or Escape closes it; with hover, delays drive it and outside clicks are ignored.
On the way to the panel, the hover bridge and safe triangle hold it open: crossing the offset gap, resting on the panel padding, or passing another hover trigger diagonally neither closes it nor hands it away.

Technologies

Built on TxTooltip (layer="menu"); the shared anchor-delay service schedules its delays and closes other panels on the same layer.
Source: packages/tuffex/packages/components/src/popover/.

查看源码

packages/tuffex/packages/components/src/popover/index.ts