GlassSurface
A glass container that refracts what is behind it, with an optional lens.
Usage
Basic
Parameter Tuning
Liquid Lens
The default, classic, bends what is behind it through a displacement ramp, which reads as distortion; engine="lens" switches to a physically modelled lens whose rim (bezel) pulls the picture behind it inward by the index of refraction while the middle stays almost as it was, and zoom, dispersion, and rimSaturation adjust the magnification, the colour split, and the edge colour.
Liquid Drag
useLiquidDrag makes the lens behave like a drop of liquid glass that lifts, stretches along the drag, and springs back on either engine; a drag writes only transform and --tx-glass-lift, so the layout size and the refraction map stay put, and glass that should answer a hover or a touch rather than a drag uses TouchSurface with surface="glass".
Best Practices
- Use it only where artwork, images, or gradients benefit from refraction; use
TxBaseSurfaceorTxCardfor regular cards. - Set
width,height, andborderRadiusexplicitly when the glass sits over scrolling content or images, and tuneblur,backgroundOpacity, andsaturationagainst the real background so text behind stays readable. - Use
useLiquidDrag, on either engine, when the rim should flow like liquid as it is dragged, andTxTouchSurfacewhen the glass should answer a hover or a touch; keep still cards and panels on the default engine orTxBaseSurface. - The lens refracts only in Chromium engines (Chrome, Edge, Electron); Safari and Firefox show frosted glass, so do not make anything readable only through the refraction. A
zoomabove 1 softens the middle, so keepzoomat 1 for a control that holds text. - Each lens is a backdrop filter that is recomputed with the page behind it, so put only as many on screen as you need.
API Reference
Props
| Property | Type | Default | Description |
|---|---|---|---|
| width | Surface width; numbers are px, strings are used as-is. | ||
| height | Surface height; numbers are px, strings are used as-is. | ||
| borderRadius | Outer radius in px, also used by the displacement map; the lens caps it at half the short side. | ||
| engine | Rendering engine. classic is the displacement-ramp glass and reads this table's props; lens refracts through a modelled convex bezel and reads the next table's. Both share width, height, borderRadius, backgroundOpacity, and saturation. | ||
| borderWidth | Edge-size multiplier of the displacement map mask. | ||
| brightness | Lightness percentage of the map's inner mask. | ||
| opacity | Alpha of the map's inner mask. | ||
| blur | Blur radius of the map mask; also the blur of the backdrop-filter fallback. | ||
| displace | Final blur (feGaussianBlur.stdDeviation) after the RGB maps are blended. | ||
| backgroundOpacity | Background alpha on the SVG-filter path; under lens it is the opacity of the background veil, and at least 0.22 when the lens falls back to frosted glass. | ||
| saturation | Saturation on the SVG-filter path; defaults to 1.5 under lens. | ||
| distortionScale | Base displacement scale of the red, green, and blue maps. | ||
| redOffset | Red offset added to distortionScale. | ||
| greenOffset | Green offset added to distortionScale. | ||
| blueOffset | Blue offset added to distortionScale. | ||
| xChannel | X-axis channel read by all three maps. | ||
| yChannel | Y-axis channel read by all three maps. | ||
| mixBlendMode | Blend mode of the blue gradient when the map is generated. |
Lens Props (engine="lens")
| Property | Type | Default | Description |
|---|---|---|---|
| bezel | Width of the refracting rim in px, at most half the short side. | ||
| thickness | Depth of the glass in px; a thicker lens carries what is behind it further. | ||
| ior | Index of refraction, 1 to 3; the same slope bends harder as it rises. | ||
| refraction | Scales how far the rim carries the content, 0 and up. | ||
| zoom | Magnification of the middle, 1 and up; it runs as a displacement pass of its own, so the middle is resampled above 1. | ||
| profile | Cross-section of the rim. squircle is a dome with a flat top and a steep edge, circle is rounder. | ||
| rimLight | Strength of the highlight along the edge, 0 and up. | ||
| rimSaturation | Saturation of what shows through the edge; above 1 it turns vivid. | ||
| dispersion | How far red, green and blue part along the rim, 0 to 0.5. | ||
| frost | Frosting of the backdrop as a blur radius in px. |
Slots
| Slot | Props | Description |
|---|---|---|
default | - | Panel content, centered in .tx-glass-surface__content above the filter layer. |
useLiquidDrag Options
| Option | Type | Default | Description |
|---|---|---|---|
bounds | MaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null | undefined> | — | What the lens may not leave; without it the lens goes wherever the pointer does. |
disabled | MaybeRefOrGetter<boolean> | false | Pauses dragging without unmounting. |
ignore | string | — | Selector of the elements inside the lens that do not start a drag, such as buttons. |
stiffness | MaybeRefOrGetter<number> | 150 | Spring stiffness of the lift and the stretch. |
damping | MaybeRefOrGetter<number> | 19 | Spring damping; lower rings for longer, higher settles at once. |
stretch | MaybeRefOrGetter<number> | 0.00018 | Stretch along an axis per px/s of speed on it, as a share of that axis's size. |
maxStretch | MaybeRefOrGetter<number> | 0.3 | The most the lens stretches along one axis, as a share of its size. |
restHeight | MaybeRefOrGetter<number> | 1 | Height at rest, as a share of the layout height. |
pressGrow | MaybeRefOrGetter<number> | 0.1 | How much taller a press makes the lens, as a share of its rest height. |
swell | MaybeRefOrGetter<number> | 0.016 | How far the width swells per unit of speed while the lens lifts or settles. |
The first argument is the lens's element or component instance, as a ref or a getter. The numeric options are read again on every frame, so they can be bound straight to sliders. It returns { dragging, position, reset }: dragging is a read-only Ref<boolean>, position() gives the lens's offset from where layout puts it in px, and reset() puts it back. The component and useLiquidDrag are both exported from @talex-touch/tuffex/glass-surface, and from the package root.
Overview
enginedefaults toclassic, soTxBaseSurface,TxRadioGroup,TxSlider, and other internal users are unaffected; unless noted, the bullets below describeclassic.- The rendering path follows support: SVG displacement refraction with
backdrop-filter: url(), else ablur()frosted backdrop, else a translucent background with a border. Safari, Firefox, SSR, and environments withoutCSS.supportsskip refraction; the fallbacks keep size, radius, and readability but drop RGB refraction. - The displacement map is drawn as a bitmap at the measured aspect ratio, at most 256px on its long side, and stretched to fill; it is redrawn when the size or an optical prop changes. Without a 2D canvas, the map stays an SVG.
- The generated SVG is decorative, non-interactive, and sits below the content layer; under high contrast it neither refracts nor blurs, and paints the opaque overlay background instead.
lensrefracts throughbackdrop-filter: url()as well, so it refracts only in Chromium engines. Elsewhere it is frosted glass: a blur offrostor 12px, whichever is larger, under a tint of at least 0.22; shape, radius, shadows, and drag carry on.useLiquidDragtakes over the pointer on press, and the drag follows the pointer even out of the lens or the window; under reduced motion the lens lifts without easing and neither stretches nor springs.
Technologies
- Three
feDisplacementMappasses shift the red, green, and blue channels separately and recombine them into a chromatic refraction. lenstreats the rim as a rise of convex glass with the cross-sectionH(t) = (1 − (1 − t)⁴)^(1/4)(squircle). Snell's law at the surface, the indexior, and the glassthicknessgive a displacement at every point, written into the red and green channels of the map and handed tofeDisplacementMap; above 0dispersionbecomes three passes, with red and blue a little either side of green. The edge highlight is a second bitmap, and arimSaturationabove 1 adds one moresaturateover that ring alone.- The refraction profile and the spring feel are numerically based on the Liquid Glass of glisse (https://glisse.kelvinzhang.com, MIT). Source:
packages/tuffex/packages/components/src/glass-surface/.