FlipOverlay | Tuff Docs

Usage

Basic

source sets where the flip starts; headerTitle and headerDesc fill the built-in header.

Loading demo...

Best Practices

Pass the real trigger element or its DOMRect as source; null falls back to a centered card with no origin.
Keep duration near the default for stacked overlays so the shared mask and card motion stay in sync.
Put size constraints (width, maxHeight) in cardStyle and reusable visual variants in cardClass.
Use surface="mask" for normal cards, glass / refraction only when the backdrop stays readable, and pure for fully custom cards.
Prefer #header-display, #header-actions, or #header-close; #header replaces the close layout too.

API Reference

Props

Name	Type	Default	Description
`modelValue`	`boolean`	`false`	Whether the overlay is shown; bind with `v-model`.
`source`	`HTMLElement \| DOMRect \| null`	`null`	Animation origin.
`sourceRadius`	`string \| null`	`null`	Corner radius of the origin.
`duration`	`number`	`480`	Animation duration in ms.
`perspective`	`number`	`1200`	3D perspective distance.
`rotateX`	`number`	`6`	X-axis rotation.
`rotateY`	`number`	`8`	Y-axis rotation.
`randomTilt`	`boolean`	`true`	Adds a slight random tilt on each open.
`tiltRange`	`number`	`2`	Range of the random tilt.
`easeOut`	`string`	`'back.out(1.25)'`	Open easing.
`easeIn`	`string`	`'back.in(1)'`	Close easing.
`maskClosable`	`boolean`	`true`	Closes on a mask click or Escape.
`preventAccidentalClose`	`boolean`	`false`	Blocks mask close and page exit, flashing a red warning glow.
`globalMask`	`boolean`	`true`	Renders the shared body-level mask.
`surface`	`'pure' \| 'mask' \| 'blur' \| 'glass' \| 'refraction'`	`'mask'`	Built-in card surface.
`surfaceColor`	`string`	`''`	Surface base color; follows the theme by default.
`surfaceOpacity`	`number`	`0.96`	Surface opacity in `mask` mode.
`speedBoost`	`number`	`1.12`	Time-scale boost after `speedBoostAt` progress.
`speedBoostAt`	`number`	`0.7`	Animation progress at which `speedBoost` starts.
`transitionName`	`string`	`'TxFlipOverlay-Mask'`	Vue transition name for the mask.
`header`	`boolean`	`true`	Renders the built-in header; ignored when `#header` is provided.
`headerTitle`	`string`	`''`	Built-in header title, wired to `aria-labelledby`.
`headerDesc`	`string`	`''`	Built-in header description, wired to `aria-describedby`.
`closable`	`boolean`	`true`	Shows the close area, including `#header-close`.
`closeAriaLabel`	`string`	`'Close'`	`aria-label` of the close button.
`maskClass`	`string`	`''`	Mask class.
`cardClass`	`string`	`''`	Card class.
`cardStyle`	`CSSProperties`	-	Inline style for the card.
`border`	`'solid' \| 'dashed' \| 'dash' \| 'none'`	`'solid'`	Card border; `dash` aliases `dashed`.
`scrollable`	`boolean`	`true`	Scrolls the body area internally.
`expanded`	`boolean`	-	Controlled expanded-motion state for UI that must stay in sync.
`animating`	`boolean`	-	Controlled animation state for UI that must stay in sync.

Events

Event	Params	Description
`update:modelValue`	`(value: boolean)`	Emits `false` when the overlay closes itself.
`open`	-	The open animation starts.
`opened`	-	The open animation ends.
`close`	-	The close animation starts.
`closed`	-	The close animation ends.
`update:expanded`	`(value: boolean)`	Syncs `expanded`.
`update:animating`	`(value: boolean)`	Syncs `animating`.

Slots

Slot	Params	Description
`default`	`{ close, expanded, animating, closable, headerTitle, headerDesc }`	Body content.
`header`	`{ close, expanded, animating, closable, headerTitle, headerDesc }`	Replaces the whole built-in header.
`header-display`	`{ close, expanded, animating, closable, headerTitle, headerDesc }`	Title and description area.
`header-actions`	`{ close, expanded, animating, closable, headerTitle, headerDesc }`	Actions left of the close button.
`header-close`	`{ close, expanded, animating, closable, headerTitle, headerDesc }`	Close area; not rendered when `closable=false`.

Exposed Methods

Method	Type	Description
`close()`	`() => void`	Runs the full close animation and emits `update:modelValue(false)`.

Overview

The overlay teleports to <body>; non-prop attributes land on the mask.
Closing emits close, update:modelValue(false), then closed; it fully closes once the parent writes v-model back.
Mask clicks and Escape obey maskClosable and flash the warning under preventAccidentalClose; the close button and close() bypass both.
Header priority: #header overrides the built-in header; otherwise header decides whether it renders.
With globalMask, stacked overlays share one mask and only the top one takes clicks; similar-sized neighbors offset (up to 3 layers) and deeper layers fade out.
The card is role="dialog" with aria-modal="true"; focus moves into it on open and returns to the previously focused element on close.

Technologies

The flip runs on lazily loaded GSAP tweens in flip-overlay-motion.ts.
Source: packages/tuffex/packages/components/src/flip-overlay/.

查看源码

packages/tuffex/packages/components/src/flip-overlay/index.ts