TouchSurface
Any surface that flows like liquid glass under hover or touch.
Usage
Basic
TxTouchSurface is a surface with a touch effect on it. Under a hovering mouse or a finger it lifts, leans toward the pointer, stretches along the way the pointer moves, and springs back when the pointer goes. It is TxBaseSurface unless you say otherwise, and every attribute it does not own goes to the surface.
Choosing the Surface
surface picks what the effect is laid on: 'base' (the default) is TxBaseSurface, 'glass' is TxGlassSurface. The rest of the attributes are the surface's own, so the material, the radius and the glass engine are set exactly as they are on the surface itself.
<template>
<!-- A frosted card -->
<TxTouchSurface mode="blur" :radius="18" class="card" />
<!-- The default look of the glass: distortion, on the classic engine -->
<TxTouchSurface surface="glass" :width="210" :height="150" :border-radius="75" />
<!-- The modelled lens -->
<TxTouchSurface surface="glass" engine="lens" :width="210" :height="150" :border-radius="75" />
</template>
surface also takes a component of your own, as long as its root element is the surface: the effect drives that root.
Your Own Element
useLiquidTouch is the same effect for any element or component instance, as a ref or a getter. It returns { hovered, pressed }.
<script setup lang="ts">
import { useLiquidTouch } from '@talex-touch/tuffex'
import { ref } from 'vue'
const card = ref<HTMLElement | null>(null)
const { pressed } = useLiquidTouch(card, { lean: 0.15, pressGrow: 0.08 })
</script>
<template>
<div ref="card" class="card" :class="{ held: pressed }">
Hold me
</div>
</template>
Best Practices
- Use it on surfaces meant to be touched, such as cards, buttons, chips, and tiles; leave still panels alone.
- The surface moves a few pixels and grows a few percent, so leave room around it. A parent with
overflow: hiddencrops it. - Keep
maxLeanandmaxStretchsmall on surfaces that hold text: the content deforms with the surface. - A finger that starts to scroll the page lets go of the surface. For a surface the finger should slide on, such as a handle or a pad, set
touch-action: none(orpan-x/pan-y) on it. - A touch screen has no hover, so a finger only presses: the surface lifts when the finger goes down and settles when it lifts or the page starts to scroll.
- It writes the
translateandscaleproperties while it is engaged, so atransformof your own is left alone, but your owntranslateorscaleis overridden until the surface is at rest. - Pass
disabledfor a surface that cannot be pressed right now instead of unmounting the effect.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
surface | 'base' | 'glass' | Component | 'base' | What the effect is laid on: TxBaseSurface, TxGlassSurface, or a component of your own whose root is the surface. |
disabled | boolean | false | Turns the effect off; a held surface lets go and springs back. |
lean | number | 0.1 | How far it leans toward the pointer, as a share of half its size, with the pointer at its edge. |
maxLean | number | 12 | The most it leans, px. |
hoverLift | number | 0.3 | Lift under a hovering mouse or pen, 0 to 1; a press or a finger lifts it fully (1). |
pressGrow | number | 0.06 | How much larger a full lift makes it, as a share of its size. |
stretch | number | 0.0001 | Stretch along an axis per px/s of pointer speed on it, as a share of the size on that axis. |
maxStretch | number | 0.2 | The most it stretches along one axis, as a share of its size. |
swell | number | 0.016 | How far the width swells per unit of speed while the lift changes. |
stiffness | number | 150 | Spring stiffness of the lift, the lean, and the stretch. |
damping | number | 19 | Spring damping; lower rings for longer, higher settles at once. |
Every other attribute, and the default slot, go to the surface.
useLiquidTouch Options
| Option | Type | Default | Description |
|---|---|---|---|
disabled | MaybeRefOrGetter<boolean> | false | Turns the effect off. |
lean | MaybeRefOrGetter<number> | 0.1 | Lean toward the pointer, as a share of half its size. |
maxLean | MaybeRefOrGetter<number> | 12 | The most it leans, px. |
hoverLift | MaybeRefOrGetter<number> | 0.3 | Lift under a hovering mouse or pen. |
pressGrow | MaybeRefOrGetter<number> | 0.06 | How much larger a full lift makes it. |
stretch | MaybeRefOrGetter<number> | 0.0001 | Stretch per px/s of pointer speed, as a share of the size. |
maxStretch | MaybeRefOrGetter<number> | 0.2 | The most it stretches along one axis. |
swell | MaybeRefOrGetter<number> | 0.016 | Width swell per unit of lift speed. |
stiffness | MaybeRefOrGetter<number> | 150 | Spring stiffness. |
damping | MaybeRefOrGetter<number> | 19 | Spring damping. |
The first argument is the 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 { hovered, pressed }, two read-only Ref<boolean>: hovered is true while a mouse or pen is over the element (never for a finger), and pressed while the primary button or a finger is down on it, wherever the pointer has gone since. TxTouchSurface and useLiquidTouch are both exported from @talex-touch/tuffex/touch-surface, and from the package root.
Slots
| Slot | Props | Description |
|---|---|---|
default | - | The surface's content. |
Overview
- Three things happen at once, all on one spring: the surface lifts (hover to
hoverLift, a press to 1), leans toward the pointer (the pointer's place from the middle, in half-sizes, timeslean, capped bymaxLean), and stretches along the way the pointer moves, thinner across it, so its volume holds. - Only the shape changes, as
translateandscale: the surface keeps the size layout gave it, and a glass surface keeps its refraction map. At rest nothing is written at all. - A glass lens reads the lift through
--tx-glass-lift, which the effect sets, so its shadows rise and fall with it. - A mouse presses with the primary button only, and a control-click is ignored. A press is followed from
window, so it carries on when the pointer leaves the surface, and a mouse that moves with no button down ends it, in case the release was lost. - A finger lifts the surface at once, leans it toward the touch, and lets go when the finger does. If the browser takes the gesture for a scroll, it sends
pointercanceland the surface lets go too. - Under reduced motion the lift applies without easing and nothing leans or stretches.
- The frame loop sleeps as soon as everything is at rest.
- The surface keeps its own support limits: a glass surface refracts only in Chromium engines (Chrome, Edge, Electron) and is frosted glass elsewhere, and the touch effect is the same either way.
Technologies
- The spring is
stepSpringfrom@talex-touch/tuffex/utils, stepped from onerequestAnimationFrameloop; the pointer's speed is a low-pass of its movement, so a mouse's jitter does not read as a swipe. - The effect uses the
translateandscaleproperties, nottransform, so a surface with its owntransformanimation keeps it. - The spring and the swell are those of
useLiquidDrag, so a dragged lens and a touched surface feel like one liquid. - Source:
packages/tuffex/packages/components/src/touch-surface/.