---
title: "BaseSurface"
description: "A background layer with switchable materials and motion fallback."
category: Primitives
status: beta
since: 0.3.4
tags: [surface, background, blur, glass, backdrop-filter, fallback]
syncStatus: reviewed
verified: true
---

## Usage

### Modes
`mode` picks the material: `pure` solid, `mask` translucent overlay, `blur` backdrop blur, `glass`, or `refraction`.
:::TuffDemoWrapper{demo="BaseSurfaceModesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxBaseSurface mode="pure">Pure</TxBaseSurface>
    <TxBaseSurface mode="mask" :opacity="0.6">Mask</TxBaseSurface>
    <TxBaseSurface mode="blur" :blur="8">Blur</TxBaseSurface>
    <TxBaseSurface mode="glass" :blur="12" :saturation="1.8">Glass</TxBaseSurface>
    <TxBaseSurface mode="refraction" :blur="11" :displace="0.8" :distortion-scale="-200">Refraction</TxBaseSurface>
  </template>
---
:::

### Advanced Lab
`filter*` props tune the filter layer, `refraction*` props the refraction layer, and `preset="card"` applies the card tuning.
:::TuffDemoWrapper{demo="BaseSurfaceAdvancedDemo" code-lang="vue"}
---
code: |
  <template>
    <TxBaseSurface
      mode="refraction"
      preset="card"
      :radius="18"
      :blur="24"
      :filter-saturation="1.6"
      refraction-profile="filmic"
      :refraction-strength="68"
      :refraction-angle="-24"
      :refraction-halo-opacity="0.42"
    >
      BaseSurface Advanced
    </TxBaseSurface>
  </template>
---
:::

### Fake Mode
`fake` paints the background on a pseudo-element, matching the existing `.fake-background` layering; slot content sits above it naturally.
:::TuffDemoWrapper{demo="BaseSurfaceFakeDemo" code-lang="vue"}
---
code: |
  <template>
    <TxBaseSurface fake mode="mask" :opacity="0.5" :radius="12">
      <strong>Pseudo-element background</strong>
    </TxBaseSurface>
    <TxBaseSurface fake mode="pure" :radius="12" color="var(--tx-color-primary-light-9)">
      Custom color
    </TxBaseSurface>
  </template>
---
:::

### Motion Fallback
`transform` motion breaks `backdrop-filter`; with `moving` set, the surface degrades to `fallbackMode` and recovers smoothly when it stops.
:::TuffDemoWrapper{demo="BaseSurfaceFallbackDemo" code-lang="vue"}
---
code: |
  <template>
    <TxButton @click="animating = !animating">
      {{ animating ? 'Stop Motion' : 'Start Motion' }}
    </TxButton>

    <div
      :style="{ transform: animating ? 'translateX(16px) scale(0.92)' : 'none' }"
      style="transition: transform 1.4s;"
    >
      <TxBaseSurface mode="glass" :blur="12">No fallback</TxBaseSurface>
      <TxBaseSurface mode="glass" :blur="12" :moving="animating" fallback-mode="mask">
        With fallback
      </TxBaseSurface>
    </div>
  </template>
---
:::

### Raw vs BaseSurface
When the motion state isn't available, turn on `autoDetect` and the surface watches transform transitions itself.
:::TuffDemoWrapper{demo="BaseSurfaceMotionCompareDemo" code-lang="vue"}
---
code: |
  <template>
    <div
      :style="{ transform: animating ? 'translateX(20px)' : '' }"
      style="backdrop-filter: blur(12px); transition: transform 1.2s;"
    >
      Raw glass (breaks on move)
    </div>

    <TxBaseSurface mode="glass" :blur="12" :moving="animating" auto-detect fallback-mode="mask">
      BaseSurface (degrades to mask)
    </TxBaseSurface>
  </template>
---
:::

### Best Practices

- Prefer `TxCard` for product containers, since it owns container semantics and interaction; use `TxBaseSurface` only to tune material, fallback, or refraction directly.
- Pass `moving` when the parent owns the animation state; use `autoDetect` only for transform transitions whose state you can't reach.
- Keep `fallbackMode="mask"` so `blur` / `glass` content stays readable in motion; use `pure` only when a flat color is acceptable.
- Tune refraction through `refractionStrength`, `refractionProfile`, and `refractionTone`; 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

- `pure` renders only the root background; `mask` renders a mask layer with opacity clamped to `0..1`.
- `blur` and `glass` degrade while `moving` is set or transform motion is detected: `fallbackMode="mask"` prefers `fallbackMaskOpacity`, and `pure` renders no mask layer.
- `refraction` keeps 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`, or `refractionProfile` switches to the derived refraction model; unset ones fall back to `62` / `-24` / `'filmic'`.
- `autoDetect` watches `style` changes on the root and its ancestors plus `transitionstart` / `transitionend` / `transitioncancel`, and removes its listeners on unmount.

## Technologies

- Glass and refraction render through `TxGlassSurface`; fallback timing lives in `base-surface-motion.ts`.
- Source: `packages/tuffex/packages/components/src/base-surface/`.

<TuffDocSourceLink />