Components/GlassSurface

GlassSurface

A glass container that refracts what is behind it, with an optional lens.

VerifiedSince 0.3.4

Usage

Basic

Loading demo...

Parameter Tuning

Loading demo...

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.

Loading demo...

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".

Loading demo...

Best Practices

  • Use it only where artwork, images, or gradients benefit from refraction; use TxBaseSurface or TxCard for regular cards.
  • Set width, height, and borderRadius explicitly when the glass sits over scrolling content or images, and tune blur, backgroundOpacity, and saturation against the real background so text behind stays readable.
  • Use useLiquidDrag, on either engine, when the rim should flow like liquid as it is dragged, and TxTouchSurface when the glass should answer a hover or a touch; keep still cards and panels on the default engine or TxBaseSurface.
  • 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 zoom above 1 softens the middle, so keep zoom at 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

PropertyTypeDefaultDescription
widthSurface width; numbers are px, strings are used as-is.
heightSurface height; numbers are px, strings are used as-is.
borderRadiusOuter radius in px, also used by the displacement map; the lens caps it at half the short side.
engineRendering 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.
borderWidthEdge-size multiplier of the displacement map mask.
brightnessLightness percentage of the map's inner mask.
opacityAlpha of the map's inner mask.
blurBlur radius of the map mask; also the blur of the backdrop-filter fallback.
displaceFinal blur (feGaussianBlur.stdDeviation) after the RGB maps are blended.
backgroundOpacityBackground 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.
saturationSaturation on the SVG-filter path; defaults to 1.5 under lens.
distortionScaleBase displacement scale of the red, green, and blue maps.
redOffsetRed offset added to distortionScale.
greenOffsetGreen offset added to distortionScale.
blueOffsetBlue offset added to distortionScale.
xChannelX-axis channel read by all three maps.
yChannelY-axis channel read by all three maps.
mixBlendModeBlend mode of the blue gradient when the map is generated.

Lens Props (engine="lens")

PropertyTypeDefaultDescription
bezelWidth of the refracting rim in px, at most half the short side.
thicknessDepth of the glass in px; a thicker lens carries what is behind it further.
iorIndex of refraction, 1 to 3; the same slope bends harder as it rises.
refractionScales how far the rim carries the content, 0 and up.
zoomMagnification of the middle, 1 and up; it runs as a displacement pass of its own, so the middle is resampled above 1.
profileCross-section of the rim. squircle is a dome with a flat top and a steep edge, circle is rounder.
rimLightStrength of the highlight along the edge, 0 and up.
rimSaturationSaturation of what shows through the edge; above 1 it turns vivid.
dispersionHow far red, green and blue part along the rim, 0 to 0.5.
frostFrosting of the backdrop as a blur radius in px.

Slots

SlotPropsDescription
default-Panel content, centered in .tx-glass-surface__content above the filter layer.

useLiquidDrag Options

OptionTypeDefaultDescription
boundsMaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null | undefined>—What the lens may not leave; without it the lens goes wherever the pointer does.
disabledMaybeRefOrGetter<boolean>falsePauses dragging without unmounting.
ignorestring—Selector of the elements inside the lens that do not start a drag, such as buttons.
stiffnessMaybeRefOrGetter<number>150Spring stiffness of the lift and the stretch.
dampingMaybeRefOrGetter<number>19Spring damping; lower rings for longer, higher settles at once.
stretchMaybeRefOrGetter<number>0.00018Stretch along an axis per px/s of speed on it, as a share of that axis's size.
maxStretchMaybeRefOrGetter<number>0.3The most the lens stretches along one axis, as a share of its size.
restHeightMaybeRefOrGetter<number>1Height at rest, as a share of the layout height.
pressGrowMaybeRefOrGetter<number>0.1How much taller a press makes the lens, as a share of its rest height.
swellMaybeRefOrGetter<number>0.016How 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

  • engine defaults to classic, so TxBaseSurface, TxRadioGroup, TxSlider, and other internal users are unaffected; unless noted, the bullets below describe classic.
  • The rendering path follows support: SVG displacement refraction with backdrop-filter: url(), else a blur() frosted backdrop, else a translucent background with a border. Safari, Firefox, SSR, and environments without CSS.supports skip 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.
  • lens refracts through backdrop-filter: url() as well, so it refracts only in Chromium engines. Elsewhere it is frosted glass: a blur of frost or 12px, whichever is larger, under a tint of at least 0.22; shape, radius, shadows, and drag carry on.
  • useLiquidDrag takes 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 feDisplacementMap passes shift the red, green, and blue channels separately and recombine them into a chromatic refraction.
  • lens treats the rim as a rise of convex glass with the cross-section H(t) = (1 − (1 − t)⁴)^(1/4) (squircle). Snell's law at the surface, the index ior, and the glass thickness give a displacement at every point, written into the red and green channels of the map and handed to feDisplacementMap; above 0 dispersion becomes three passes, with red and blue a little either side of green. The edge highlight is a second bitmap, and a rimSaturation above 1 adds one more saturate over 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/.
查看源码
packages/tuffex/packages/components/src/glass-surface/index.ts