GitHub - justintaddei/v-wave: The material-ripple directive for Vue that actually works

v-wave

The material-ripple directive for Vue that actually works

_{Also available for React: use-wave}

Why did I make this?

Because every ripple plugin I've tried to use in the past either didn't work or was missing basic features.

Here's what you can expect from this plugin:

It works (see for yourself).
The wave appears on pointerdown instead of pointerup
(you might think that's an obvious choice... but you'd be wrong).
The wave responds to keyboard events on keyboard-accessible elements (i.e. Enter and Space on <button>).
There is a small delay before the ripple appears, during which the animation will be canceled if the user moves the pointer (e.g. scrolling on a mobile phone). This is similar to how native Android ripples work.
Uses CSS transforms instead of width and height.
Doesn't affect the appearance of the element you apply it to (won't explode when used on an element with display: flex).
Guesses the color of the wave automatically by default (using currentColor).
Works with fixed, absolute, relative, and statically positioned elements.
Will handle independent border-radii (e.g. border-radius: 5px 20px 15px 30px) perfectly fine.

[Live Demo]

Quick start

After installing and registering the plugin, this is all you need to get started:

<button v-wave>Click here</button>

Out of the box, this will provide you with a ripple that matches the text color of the element it has been applied to, with reasonable defaults for a responsive feeling ripple.
You can change the look and feel of the ripple on a per-element basis, or by modifying the global defaults.

Installation

See: npm, cdn

Via NPM

See: Vue, Nuxt

$ npm i v-wave

Vue

import { createApp } from 'vue'
import VWave from 'v-wave'
import App from './App.vue'

const app = createApp(App)

app.use(VWave)

// Vue 2

import Vue from 'vue'
import VWave from 'v-wave'

Vue.use(VWave)

or

Nuxt

// nuxt.config.js

// Nuxt 3
export default {
    modules: ['v-wave/nuxt']
}

// Nuxt 2
export default {
    modules: ['v-wave/nuxt/v2']
}

Via CDN

Expand examples

<script src="https://unpkg.com/v-wave"></script>

// With a CDN, `VWave` is made available as a global
Vue.use(VWave)

Configuration

See: configuring globally, configuring locally

Configuring globally

See: Vue, Nuxt

Vue

import { createApp } from 'vue'
import VWave from 'v-wave'
import App from './App.vue'

const app = createApp(App)

app.use(VWave, {
  color: 'red',
  initialOpacity: 0.5,
  easing: 'ease-in'
})

// Vue 2

import Vue from 'vue'
import VWave from 'v-wave'

Vue.use(VWave, {
  color: 'red',
  initialOpacity: 0.5,
  easing: 'ease-in'
})

or

Nuxt

// nuxt.config.js

export default {
  modules: ['v-wave/nuxt'],
  vWave: {
    color: 'red',
    initialOpacity: 0.5,
    easing: 'ease-in'
  }
}

Configuring locally

<button
  v-wave="{
    color: 'red',
    initialOpacity: 0.5,
    easing: 'ease-in',
}"
>
  Click here
</button>

Options

See: summary, details

Summary

Name	Default	Type
color	`"currentColor"`	`string`
initialOpacity	`0.2`	`number`
finalOpacity	`0.1`	`number`
duration	`0.4`	`number`
dissolveDuration	`0.15`	`number`
waitForRelease	`true`	`boolean`
easing	`ease-out`	`string`
cancellationPeriod	`75`	`number`
trigger	`"auto"`	`string \| boolean \| "auto"`
disabled	`false`	`boolean`
respectDisabledAttribute	`true`	`boolean`
respectPrefersReducedMotion	`true`	`boolean`
stopPropagation	`false`	`boolean`
tagName	`"div"`	`string`

Details

color

type: string (background shorthand syntax)
default: "currentColor"

Sets the background of the ripple.
Supports any value that the CSS background property does.

Expand examples

See: color, gradient, image

Simple color

<button
  v-wave="{
    color: 'red',
}"
>
  Click here
</button>

Gradient

<button
  v-wave="{
    color: 'radial-gradient(closest-side, #fff, #00f, #fff)',
}"
>
  Click here
</button>

Image

<button
  v-wave="{
    color: 'no-repeat url(https://...) 0 0 / cover',
}"
>
  Click here
</button>

initialOpacity

type: number
default: 0.2

The opacity of the ripple when it first appears.

Expand examples

See: initialOpacity: 1, initialOpacity: 0

initialOpacity of 1

<button
  v-wave="{
    initialOpacity: 1,
}"
>
  Click here
</button>

initialOpacity of 0

<button
  v-wave="{
    initialOpacity: 0,
}"
>
  Click here
</button>

finalOpacity

type: number
default: 0.1

The opacity the ripple should be when it has stopped moving.

Expand examples

See: finalOpacity: 1, finalOpacity: 0

finalOpacity of 1

<button
  v-wave="{
    finalOpacity: 1,
}"
>
  Click here
</button>

finalOpacity of 0

<button
  v-wave="{
    finalOpacity: 0,
}"
>
  Click here
</button>

duration

type: number (seconds)
default: 0.4

The duration of the ripple in seconds.
The total duration is duration + dissolveDuration

Expand example

duration of 3 seconds

<button
  v-wave="{
    duration: 3,
}"
>
  Click here
</button>

dissolveDuration

type: number (seconds)
default: 0.15

The duration of the "dissolve animation" in seconds.
This is the fade-out animation that plays once the wave has reached its maximum size.
The total duration is duration + dissolveDuration

Expand example

dissolve duration of 3 seconds

<button
  v-wave="{
    dissolveDuration: 3,
}"
>
  Click here
</button>

waitForRelease

type: boolean
default: true

When true, the wave will not dissolve until the user releases the pointer.

easing

type: string (<easing-function>)
default: "ease-out"

Any valid CSS <easing-function> (see more)

Expand example

cubic-bezier

<button
  v-wave="{
    easing: 'cubic-bezier(0,.57,.89,0)',
}"
>
  Click here
</button>

cancellationPeriod

type: number (milliseconds)
default: 75

The delay, in milliseconds, during which the animation will be canceled if the user moves their figure/pointer (e.g. while scrolling on a mobile device).

Note: The ripple will not appear until after the delay. This means a delay greater than 100ms can feel sluggish.

trigger

type: "auto" | string | boolean
default: "auto"

Sets the behavior of the wave when used with triggers. (See the dedicated section on triggers for more details).

false
Disables the use of triggers. If a v-wave-trigger (without an ID) is present in the dom tree of this element, it will be ignored (i.e. v-wave always behaves as if there's no trigger).
true
Requires a trigger to activate the ripple. v-wave assumes the presence of a v-wave-trigger (without an ID) in its dom tree. The ripple will only activate for pointerdown events on the trigger element.
"auto"
If a v-wave-trigger (without an ID) is present in the dom-tree of the v-wave element, it behaves as trigger: true, otherwise it behaves as trigger: false.
string
Any string other than "auto" will be treated as an ID. v-wave will only activate when a v-wave-trigger with a matching ID receives a pointerdown event.

This is different from the other values as it allows you to place the trigger element anywhere in the dom, while the others require the trigger to be a descendant.

Expand example

basic trigger

<label v-wave>
  <input type="text" placeholder="Search" />

  <!-- Only show the wave when the trigger is clicked -->
  <img v-wave-trigger src="search.svg" />
</label>

disabled

type: boolean
default: false

Disables the wave effect on the element regardless of respectDisabledAttribute.

respectDisabledAttribute

type: boolean
default: true

When true, the wave effect will be disabled if the html disabled attribute is present on the element.

<!-- The wave will *not* appear on this button -->
<button v-wave disabled>Click me!</button>
<!-- The wave *will* appear on this button -->
<button v-wave="{respectDisabledAttribute: false}" disabled>Click me!</button>

respectPrefersReducedMotion

type: boolean
default: true

If true, the wave effect will be disabled if the user's prefers-reduced-motion preference is set to reduce.

stopPropagation

type: boolean
default: false

Prevents the pointerdown event from propagating to parent elements.

tagName

type: string
default: "div"

Sets the tag name of the element used as the wave container. This is is useful in scenarios where the default div may interfere with :last-of-type or similar selectors.

Using triggers

Triggers allow you to activate a wave on an element when, and only when, a different element receives input.

In the following example, the wave will only activate for the label element when the user clicks or taps on the <img/>.

<label v-wave>
  <span>Password</span>
  <input :type="showPassword ? 'text' : 'password'" />
  <img v-wave-trigger src="eye.svg" @click="() => showPassword = !showPassword" />
</label>

In this next example, clicking one of the buttons will activate the wave on the other button.

<button v-wave="{trigger: 'button2'}" v-wave-trigger:button1>Button 1</button>

<button v-wave="{trigger: 'button1'}" v-wave-trigger:button2>Button 2</button>

Triggers that use an ID support many-to-many relationships. See the grid example on the example page.

Advanced

Registering the directive locally

Local registration with Composition API:

<script>
  import VWave from 'v-wave'
  const { vWave, vWaveTrigger } = VWave.createLocalWaveDirective({
    /* global options */
  })
</script>

<template>
  <button v-wave>Click me!</button>
</template>

Local registration with Options API:

<script>
  import VWave from 'v-wave'
  const { wave, waveTrigger } = VWave.createLocalWaveDirective({
    /* global options */
  })

  export default {
    directives: {
      wave,
      waveTrigger
    }
  }
</script>

<template>
  <button v-wave>Click me!</button>
</template>

If you are using Vue 2, you need to pass "vue2" as the second argument to createLocalWaveDirective

<script>
  import VWave from 'v-wave'
  const { wave, waveTrigger } = VWave.createLocalWaveDirective(
    {
      /* global options */
    },
    'vue2'
  ) // this is the difference

  export default {
    directives: {
      wave,
      waveTrigger
    }
  }
</script>

<template>
  <button v-wave>Click me!</button>
</template>

Changing the directive's name

If you are migrating from another ripple directive you can change the name of the directive v-wave uses if you want to avoid changing it in your source code.
Simply pass a new name for the directive using the directive option:

//main.js

import Vue from 'vue'
import VWave from 'v-wave'

Vue.use(VWave, {
  directive: 'ripple'
})

Now you can use the plugin like so:

<button v-ripple>Click me!</button>

Keep in mind that this option can only be set globally (i.e. it cannot be set on individual directives).

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for more details.

License

This project is distributed under the MIT License.

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Name		Name	Last commit message	Last commit date
Latest commit History 1,402 Commits
.github		.github
.husky		.husky
nuxt		nuxt
src		src
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
biome.json		biome.json
commitlint.config.cjs		commitlint.config.cjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
release-please-config.json		release-please-config.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

justintaddei/v-wave

Folders and files

Latest commit

History

Repository files navigation

v-wave

Why did I make this?

[Live Demo]

Quick start

Contents

Installation

Via NPM

Vue

Nuxt

Via CDN

Configuration

Configuring globally

Vue

Nuxt

Configuring locally

Options

Summary

Details

color

Simple color

Gradient

Image

initialOpacity

initialOpacity of 1

initialOpacity of 0

finalOpacity

finalOpacity of 1

finalOpacity of 0

duration

duration of 3 seconds

dissolveDuration

dissolve duration of 3 seconds

waitForRelease

easing

cubic-bezier

cancellationPeriod

trigger

basic trigger

disabled

respectDisabledAttribute

respectPrefersReducedMotion

stopPropagation

tagName

Using triggers

Advanced

Registering the directive locally

Local registration with Composition API:

Local registration with Options API:

Changing the directive's name

Contributing

License

The MIT License (MIT)

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 3

Sponsor this project

Contributors 5

Languages