BaseSurface

Unified background rendering component — supports pure, mask, blur, glass, and refraction modes, with a built-in motion degradation mechanism that automatically resolves the well-known Chromium backdrop-filter + transform invalidation bug.

Supports fake pseudo-element rendering mode (consistent with the existing .fake-background utility). Dark mode switches automatically via the CSS variable system.

Relationship with TxCard

Use TxCard for out-of-the-box product usage (header/footer/loading/inertial/interaction states).
Use TxBaseSurface for low-level material tuning (filter/refraction/glass parameter matrix).
Recommended split: TxCard handles container semantics + interaction, TxBaseSurface handles material rendering.

Background Modes

Five modes compared: pure solid color, mask semi-transparent overlay, blur backdrop blur, glass glass layer, and refraction glass+filter refraction.

Mode Comparison

Demo will load when visible.

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap;">
    <TxBaseSurface mode="pure" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      Pure
    </TxBaseSurface>
    <TxBaseSurface mode="mask" :opacity="0.6" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      Mask
    </TxBaseSurface>
    <TxBaseSurface mode="blur" :blur="8" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      Blur
    </TxBaseSurface>
    <TxBaseSurface mode="glass" :blur="12" :saturation="1.8" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      Glass
    </TxBaseSurface>
  </div>
</template>

Advanced Parameter Lab

Use this low-level lab to tune material parameters in filter / refraction workflows. For product-facing card usage, TxCard is still the recommended first choice.

Advanced Lab

Demo will load when visible.

<script setup lang="ts">
import { ref } from 'vue'

const mode = ref<'blur' | 'glass' | 'refraction'>('refraction')
const profile = ref<'soft' | 'filmic' | 'cinematic'>('filmic')
const blur = ref(24)
const filterSaturation = ref(1.6)
const filterContrast = ref(1.05)
const filterBrightness = ref(1.02)

const refractionStrength = ref(68)
const refractionAngle = ref(-24)
const refractionHaloOpacity = ref(0.42)
</script>

<template>
  <TxBaseSurface
    :mode="mode"
    preset="card"
    :radius="18"
    :blur="blur"
    :filter-saturation="filterSaturation"
    :filter-contrast="filterContrast"
    :filter-brightness="filterBrightness"
    :refraction-profile="profile"
    :refraction-strength="refractionStrength"
    :refraction-angle="refractionAngle"
    :refraction-halo-opacity="refractionHaloOpacity"
    style="min-height: 180px; padding: 16px;"
  >
    BaseSurface Advanced
  </TxBaseSurface>
</template>

Fake Pseudo-Element Mode

Enable pseudo-element background rendering via the fake prop. Slot content naturally sits above the background without extra z-index management. Useful when you need consistency with the existing .fake-background pattern.

Fake Mode

Demo will load when visible.

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap;">
    <TxBaseSurface fake mode="mask" :opacity="0.5" :radius="12" style="width: 200px; height: 100px;">
      <strong>Pseudo-element background</strong>
      <span style="font-size: 12px; opacity: 0.7;">Slot content naturally above</span>
    </TxBaseSurface>
    <TxBaseSurface fake mode="pure" :radius="12" color="var(--tx-color-primary-light-9)" style="width: 200px; height: 100px;">
      Custom color
    </TxBaseSurface>
  </div>
</template>

Motion Fallback

When blur or glass mode elements are in a CSS transform animation, backdrop-filter becomes invalidated (known Chromium bug).

Use the moving prop for manual control, or auto-detect for automatic transform detection. The component degrades to fallbackMode (default mask) during motion and smoothly recovers afterward.

Click the button to trigger real transform movement on both blur and glass cards. The cards contain scrollable content inside.

Multi-Mode Motion Fallback

Demo will load when visible.

<script setup lang="ts">
import { ref } from 'vue'

const animating = ref(false)
</script>

<template>
  <TxBaseSurface
    mode="glass"
    :blur="12"
    :moving="animating"
    fallback-mode="mask"
    :radius="14"
  >
    <div style="max-height: 140px; overflow-y: auto;">
      Scrollable content...
    </div>
  </TxBaseSurface>
  <TxButton @click="animating = !animating">
    {{ animating ? 'Stop' : 'Start Motion' }}
  </TxButton>
</template>

Raw vs BaseSurface Comparison

Left side uses raw backdrop-filter — blur breaks completely during transform motion. Right side uses BaseSurface — gracefully degrades to mask during motion, then smoothly recovers to glass when stopped.

Motion Comparison

Demo will load when visible.

<script setup lang="ts">
import { ref } from 'vue'

const animating = ref(false)
</script>

<template>
  <!-- Left: raw, backdrop-filter breaks on move -->
  <div :style="{ transform: animating ? 'translateX(20px)' : '' }"
       style="backdrop-filter: blur(12px); transition: transform 1.2s;">
    Raw glass (breaks on move)
  </div>

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

API

TxBaseSurface Props

Prop	Type	Default	Description
`mode`	`'pure' \| 'mask' \| 'blur' \| 'glass' \| 'refraction'`	`'pure'`	Surface mode: pure / mask / filter / glass / refraction.
`radius`	`string \| number`	-	Custom border radius (inherits from parent if unset).
`color`	`string`	-	Base color for pure/mask layers.
`opacity`	`number`	`0.75`	Opacity in `mask` mode (0-1).
`fallbackMaskOpacity`	`number`	-	Overrides opacity when degraded to `mask` (0-1).
`blur`	`number`	`10`	Blur intensity for the filter layer (px).
`filterSaturation`	`number`	`1.5`	Filter-layer saturation (low-level tuning).
`filterContrast`	`number`	`1`	Filter-layer contrast (low-level tuning).
`filterBrightness`	`number`	`1`	Filter-layer brightness (low-level tuning).
`saturation`	`number`	`1.8`	Glass-layer saturation for glass/refraction.
`brightness`	`number`	`70`	Glass-layer brightness for glass/refraction.
`backgroundOpacity`	`number`	`0`	Background opacity of the glass layer.
`borderWidth`	`number`	`0.07`	Edge width factor for 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 for spectral separation.
`xChannel` / `yChannel`	`'R' \| 'G' \| 'B'`	`'R' / 'G'`	Sampling channels used by displacement maps.
`mixBlendMode`	`string`	`'difference'`	Blend mode used in refraction rendering.
`refractionStrength`	`number`	-	Unified refraction strength (0-100).
`refractionProfile`	`'soft' \| 'filmic' \| 'cinematic'`	-	Refraction style preset.
`refractionTone`	`'mist' \| 'balanced' \| 'vivid'`	`'balanced'`	Refraction tone preset (`vivid` is clearer, `mist` is softer).
`refractionAngle`	`number`	-	Main dispersion angle in degrees.
`refractionLightX` / `refractionLightY`	`number`	-	Light anchor coordinates (0-1).
`refractionHaloOpacity`	`number`	-	Halo opacity override (0-1). If unset, uses the internal filmic model.
`overlayOpacity`	`number`	`0`	Optional extra mask opacity for non-mask modes.
`preset`	`'default' \| 'card'`	`'default'`	Visual preset (`card` applies card-focused tuning).
`refractionRenderer`	`'svg' \| 'css'`	`'svg'`	Renderer type for refraction mode.
`moving`	`boolean`	`false`	Manual motion flag for degradation fallback.
`fallbackMode`	`'pure' \| 'mask'`	`'mask'`	Target mode while moving.
`settleDelay`	`number`	`150`	Delay before recovery after motion ends (ms).
`autoDetect`	`boolean`	`false`	Auto detect transform motion and fallback.
`transitionDuration`	`number`	`260`	Recovery transition duration (ms).
`fake`	`boolean`	`false`	Enable fake pseudo-element rendering mode.
`fakeIndex`	`number`	`0`	z-index for fake layer.
`tag`	`string`	`'div'`	Root element tag name.

Slots

Slot	Description
`default`	Surface content.

CSS Variables

Variable	Description	Light Default	Dark Default
`--tx-surface-color`	Solid/mask background color	`var(--tx-fill-color-lighter)` (#fafafa)	#1d1d1d
`--tx-surface-blur-bg`	Semi-transparent base for blur/glass	`rgba(255,255,255,0.6)`	`rgba(0,0,0,0.4)`

Interaction Contract

tag controls the root element and the default slot is rendered above all material layers.
pure mode renders only the root background; mask renders the mask layer and clamps opacity to 0..1.
blur and glass degrade while moving=true or auto-detected transform motion is active. fallbackMode='mask' uses fallbackMaskOpacity when provided; fallbackMode='pure' renders no mask layer.
glass and refraction forward normalized geometry and optical props to TxGlassSurface.
refraction adds glass, filter, mask, and edge layers, plus renderer/profile/tone classes and light/strength CSS variables.
autoDetect observes the root and ancestor style/transition changes and tears listeners/observers down on unmount.