Components/FlipOverlay

FlipOverlay

A 3D overlay that flips open from its trigger.

VerifiedSince 0.3.4

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.
  • The card surface defaults to refraction. It renders in fake mode over a translucent surfaceColor base, 50% opaque by default: enough to keep text legible while the page behind still shows through to be blurred and refracted. Under mask the base defaults to 96%. surfaceOpacity changes either, and pure suits fully custom cards.
  • Prefer #header-display, #header-actions, or #header-close; #header replaces the close layout too.

API Reference

Props

NameTypeDefaultDescription
modelValuebooleanfalseWhether the overlay is shown; bind with v-model.
sourceHTMLElement | DOMRect | nullnullAnimation origin.
sourceRadiusstring | nullnullCorner radius of the origin.
durationnumber480Animation duration in ms.
perspectivenumber12003D perspective distance.
rotateXnumber6X-axis rotation.
rotateYnumber8Y-axis rotation.
randomTiltbooleantrueAdds a slight random tilt on each open.
tiltRangenumber2Range of the random tilt.
easeOutstring'back.out(1.25)'Open easing.
easeInstring'back.in(1)'Close easing.
maskClosablebooleantrueCloses on a mask click or Escape.
preventAccidentalClosebooleanfalseBlocks mask close and page exit, flashing a red warning glow.
globalMaskbooleantrueRenders the shared body-level mask.
surface'pure' | 'mask' | 'blur' | 'glass' | 'refraction' | 'acrylic' | 'mica' | 'flat' | 'plain''refraction'Built-in card surface.
surfaceColorstring''Surface base color; follows the theme by default.
surfaceOpacitynumber0.96 for mask, 0.5 otherwiseOpacity 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.
speedBoostnumber1.12Time-scale boost after speedBoostAt progress.
speedBoostAtnumber0.7Animation progress at which speedBoost starts.
transitionNamestring'TxFlipOverlay-Mask'Vue transition name for the mask.
headerbooleantrueRenders the built-in header; ignored when #header is provided.
headerTitlestring''Built-in header title, wired to aria-labelledby.
headerDescstring''Built-in header description, wired to aria-describedby.
closablebooleantrueShows the close area, including #header-close.
closeAriaLabelstring'Close'aria-label of the close button.
maskClassstring''Mask class.
cardClassstring''Card class.
cardStyleCSSProperties-Inline style for the card.
border'solid' | 'dashed' | 'dash' | 'none''solid'Card border; dash aliases dashed.
scrollablebooleantrueScrolls the body area internally.
expandedboolean-Controlled expanded-motion state for UI that must stay in sync.
animatingboolean-Controlled animation state for UI that must stay in sync.

Events

EventParamsDescription
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

SlotParamsDescription
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

MethodTypeDescription
close()() => voidRuns 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), 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, not counting one flying back; 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 Tab stays inside. Focus returns to the previously focused element as soon as the close starts, and the overlay is inert while 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