FlipOverlay
A 3D overlay that flips open from its trigger.
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
DOMRectassource;nullfalls back to a centered card with no origin. - Keep
durationnear the default for stacked overlays so the shared mask and card motion stay in sync. - Put size constraints (
width,maxHeight) incardStyleand reusable visual variants incardClass. - The card surface defaults to
refraction. It renders in fake mode over a translucentsurfaceColorbase, 50% opaque by default: enough to keep text legible while the page behind still shows through to be blurred and refracted. Undermaskthe base defaults to 96%.surfaceOpacitychanges either, andpuresuits fully custom cards. - Prefer
#header-display,#header-actions, or#header-close;#headerreplaces 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' | 'acrylic' | 'mica' | 'flat' | 'plain' | 'refraction' | Built-in card surface. |
surfaceColor | string | '' | Surface base color; follows the theme by default. |
surfaceOpacity | number | 0.96 for mask, 0.5 otherwise | Opacity of the card's base colour, used by mask, blur, acrylic, glass and refraction; always opaque under pure and flat, and mica and plain lay no base colour. |
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. - With an element as
source, the card flies out of the part of it that shows, and back into it on close: one partly scrolled out of its container starts from its visible part. - Closing emits
close,update:modelValue(false), thenclosed; it fully closes once the parent writesv-modelback. - Mask clicks and Escape obey
maskClosableand flash the warning underpreventAccidentalClose; the close button andclose()bypass both. - Header priority:
#headeroverrides the built-in header; otherwiseheaderdecides whether it renders. - With
globalMask, stacked overlays share one mask and only the top one takes clicks, not counting one flying back; similar-sized neighbors offset (up to 3 layers) and deeper layers fade out. - The card is
role="dialog"witharia-modal="true"; focus moves into it on open, and Tab stays inside. Focus returns to the previously focused element as soon as the close starts, and the overlay isinertwhile the card flies back, handing the pointer and the keys to the layer below.
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