Ripple

updated

Look at that subtle drift to the centre. The tasteful softness of its edge. Oh my God, it even respects reduced motion. A directive for a press ripple that grows from where you pressed and drifts to the centre.

Demo

Button, Toggle, Item links, menu and list items, tabs, accordion triggers, calendar days and the rest of the pressable parts already ripple: they import the directive themselves, so there's nothing to register for them. Install it to ripple your own elements.

Installation

Register it once in your app entry, or import it in the component that uses it, as kappa-ui's parts do:

import vRipple from '@/lib/ripple'

app.directive('ripple', vRipple)

Usage

<button v-ripple>Press me</button>
<button v-ripple="{ color: 'red', opacity: 0.3 }">Tinted</button>

On a Button, the directive overrides the built-in ripple:

<Button v-ripple="{ color: 'red', opacity: 0.3 }">Tinted</Button>
<Button v-ripple="false">Off</Button>

The wave starts small under your finger, drifts to the centre as it grows, and has a soft edge. Enter and Space ripple too, from the centre. If the element is position: static, the directive makes it relative.

No stylesheet needed: it runs on the Web Animations API. Colour, opacity and timing come from the variables below, read at the moment of the press.

  • A quick tap still shows the ripple for at least 225ms, so it never just flashes.
  • Holding keeps the wave up until you let go.
  • With reduced motion, the wave appears fully grown and only fades.
  • In forced colours mode, there's no wave at all.
  • A disabled element (disabled, aria-disabled="true" or data-disabled) doesn't ripple.
VariableDefaultDescription
--kappa-rippleunsetnone turns the ripple off for an element and everything inside it, built-in ones included; the pressed layer takes the press back. Set it on :root to go without ripples.
--kappa-ripple-colorcurrentColorColour of the wave.
--kappa-ripple-opacityvar(--state-pressed, 0.12)Opacity of the wave. Unset, the wave reads --state-pressed where it is pressed, so a subtree that changes --state-pressed changes the wave too.
--kappa-ripple-grow-duration450msTime to expand.
--kappa-ripple-fade-duration375msTime to fade after release.
--kappa-ripple-easingvar(--ease-standard, cubic-bezier(0.2, 0, 0, 1))Easing of the expansion. The ripple item sets it on :root; without it the directive uses cubic-bezier(0.2, 0, 0, 1).

Changelog

  1. core 0.11.0

    3e1a8a0 — vRipple leaves a disabled host alone (:disabled, aria-disabled="true" or data-disabled), and a v-ripple on a component that already ripples now overrides the one inside it from the first render, not only after an update.

    --kappa-ripple: none turns the ripple off for an element and everything inside it, read at the moment of the press: put it on :root to go without ripples, built-in ones included. state-layer now yields its pressed layer only while a wave is showing, so a press keeps its feedback once the ripple is off.