BaseSurface
A background layer with switchable materials and motion fallback.
Usage
Modes
mode picks the material: pure solid, mask translucent overlay, blur backdrop blur, glass, or refraction.
Loading demo...
Advanced Lab
filter* props tune the filter layer, refraction* props the refraction layer, and preset="card" applies the card tuning.
Loading demo...
Fake Mode
fake paints the background on a pseudo-element, matching the existing .fake-background layering; slot content sits above it naturally.
Loading demo...
Motion Fallback
transform motion breaks backdrop-filter; with moving set, the surface degrades to fallbackMode and recovers smoothly when it stops.
Loading demo...
Raw vs BaseSurface
When the motion state isn't available, turn on autoDetect and the surface watches transform transitions itself.
Loading demo...
Best Practices
- Prefer
TxCardfor product containers, since it owns container semantics and interaction; useTxBaseSurfaceonly to tune material, fallback, or refraction directly. - Pass
movingwhen the parent owns the animation state; useautoDetectonly for transform transitions whose state you can't reach. - Keep
fallbackMode="mask"soblur/glasscontent stays readable in motion; usepureonly when a flat color is acceptable. - Tune refraction through
refractionStrength,refractionProfile, andrefractionTone; keep RGB channel offsets for visual experiments. - Use
refractionRenderer="css"only where its lower optical fidelity is acceptable.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
mode | 'pure' | 'mask' | 'blur' | 'glass' | 'refraction' | 'pure' | Surface mode: solid, mask, filter, glass, or refraction. |
radius | string | number | - | Corner radius; inherits from the parent when unset. |
color | string | - | Base color for the solid or mask layer. |
opacity | number | 0.75 | Opacity in mask mode (0–1). |
fallbackMaskOpacity | number | - | Opacity when degraded to mask (0–1). |
blur | number | 10 | Filter-layer blur radius in px. |
filterSaturation | number | 1.5 | Filter-layer saturation. |
filterContrast | number | 1 | Filter-layer contrast. |
filterBrightness | number | 1 | Filter-layer brightness. |
saturation | number | 1.8 | Glass-layer saturation for glass and refraction. |
brightness | number | 70 | Glass-layer brightness for glass and refraction; <= 3 is read as a multiplier. |
backgroundOpacity | number | 0 | Background opacity of the glass layer. |
borderWidth | number | 0.07 | Edge width factor of the glass layer. |
displace | number | 0.5 | Refraction displacement amount. |
distortionScale | number | -180 | Refraction distortion scale. |
redOffset / greenOffset / blueOffset | number | 0 / 10 / 20 | RGB channel offsets that control dispersion. |
xChannel / yChannel | 'R' | 'G' | 'B' | 'R' / 'G' | Channels sampled by the displacement map. |
mixBlendMode | string | 'difference' | Refraction blend mode. |
refractionStrength | number | 62 | Refraction strength, 0–100. |
refractionProfile | 'soft' | 'filmic' | 'cinematic' | 'filmic' | Refraction style preset. |
refractionTone | 'mist' | 'balanced' | 'vivid' | 'balanced' | Refraction tone: vivid is clearer, mist softer. |
refractionAngle | number | -24 | Main dispersion angle in degrees. |
refractionLightX / refractionLightY | number | - | Light anchor (0–1). |
refractionHaloOpacity | number | - | Halo opacity (0–1); the built-in filmic model applies when unset. |
overlayOpacity | number | 0 | Extra mask opacity for non-mask modes. |
preset | 'default' | 'card' | 'default' | Visual preset; card applies the card tuning. |
refractionRenderer | 'svg' | 'css' | 'svg' | Refraction renderer. |
moving | boolean | false | Marks the surface as moving, which triggers the fallback. |
fallbackMode | 'pure' | 'mask' | 'mask' | Mode used while moving. |
settleDelay | number | 150 | Delay in ms before recovery after motion ends; never shorter than transitionDuration. |
autoDetect | boolean | false | Detects transform motion and falls back automatically. |
transitionDuration | number | 299 | Recovery transition duration in ms. |
fake | boolean | false | Renders the background on a pseudo-element. |
fakeIndex | number | 0 | z-index of the pseudo-element layer. |
tag | string | 'div' | Root element tag. |
Slots
| Slot | Props | Description |
|---|---|---|
default | - | Surface content, rendered in .tx-base-surface__content above every material layer. |
CSS Variables
| Variable | Source | Description |
|---|---|---|
--tx-surface-color | color prop or theme fallback | Solid / mask color; defaults to var(--tx-fill-color-lighter, #fafafa). |
--tx-surface-radius | radius prop | Radius of the root and every layer; numbers become px. |
--tx-surface-transition | transitionDuration prop | Duration of layer fades, background, and backdrop-filter transitions. |
--tx-surface-filter-blur | blur prop | Blur radius of the filter and refraction filter layers. |
--tx-surface-filter-saturation | filterSaturation prop | Filter-layer saturation multiplier. |
--tx-surface-filter-contrast | filterContrast prop | Filter-layer contrast multiplier. |
--tx-surface-filter-brightness | filterBrightness prop | Filter-layer brightness multiplier. |
--tx-surface-mask-opacity | opacity, fallbackMaskOpacity, or overlayOpacity | Current mask opacity, clamped to 0..1. |
--tx-surface-refraction-light-x / --tx-surface-refraction-light-y | refractionLightX / refractionLightY or angle model | Refraction light anchor in percent. |
--tx-surface-refraction-strength | refractionStrength model | Optical strength blended across rest, motion, and recovery. |
--tx-surface-fake-index | fakeIndex prop | z-index of the pseudo-element layer. |
--tx-surface-fake-bg | color prop or theme fallback | Background color of the pseudo-element. |
--tx-surface-fake-opacity | mask opacity model | Opacity of the pseudo-element. |
--tx-surface-mask-opacity-percent | mask opacity model | Mask opacity as a percentage (internal; do not override). |
--tx-surface-motion-cover-opacity | motion state model | Opacity of the refraction motion cover (internal). |
--tx-surface-refraction-edge-opacity | optics model | Opacity of the refraction edge highlight (internal). |
--tx-surface-refraction-streak-angle | refractionAngle model | Refraction streak angle, the angle plus 92deg (internal). |
--tx-surface-refraction-{filter,mask}-{base,primary,secondary,veil}-weight / --tx-surface-refraction-streak-weight | profile/tone weight model | Blend weights of the optical layers (internal). |
--tx-surface-refraction-*-gain / -boost / -base, --tx-surface-refraction-halo-opacity, --tx-surface-refraction-mask-effective-opacity | profile/tone derived values | Derived outputs of the optical interpolation (internal). |
--tx-surface-refraction-mask-color | theming hook (consumed) | Base color of the refraction gradients; override it in themes (defaults to #fff shades). |
Overview
purerenders only the root background;maskrenders a mask layer with opacity clamped to0..1.blurandglassdegrade whilemovingis set or transform motion is detected:fallbackMode="mask"prefersfallbackMaskOpacity, andpurerenders no mask layer.refractionkeeps its mode in motion: the glass / blur layers that lose their sampling fade out, a translucent motion cover holds the weight, and both cross-fade back on settle.- Passing any of
refractionStrength,refractionAngle, orrefractionProfileswitches to the derived refraction model; unset ones fall back to62/-24/'filmic'. autoDetectwatchesstylechanges on the root and its ancestors plustransitionstart/transitionend/transitioncancel, and removes its listeners on unmount.
Technologies
- Glass and refraction render through
TxGlassSurface; fallback timing lives inbase-surface-motion.ts. - Source:
packages/tuffex/packages/components/src/base-surface/.
查看源码
packages/tuffex/packages/components/src/base-surface/index.ts