BaseSurface
Unified background rendering component supporting pure/mask/blur/glass/refraction modes with motion-degradation fallback for backdrop-filter + transform issues.
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
TxCardfor out-of-the-box product usage (header/footer/loading/inertial/interaction states). - Use
TxBaseSurfacefor low-level material tuning (filter/refraction/glass parameter matrix). - Recommended split:
TxCardhandles container semantics + interaction,TxBaseSurfacehandles 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
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
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
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
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
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) |