The material-ripple directive for Vue that actually works

by Vue.js Examples

v-wave

The material-ripple directive for Vue that actually works.

View Demo View Github

Here's what you can expect from this plugin:

  • It works.
  • The wave appears on pointerdown instead of pointerup
    (you might think that's an obvious choice... but you'd be wrong).
  • 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 effect 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.

Install

npm

$ npm i v-wave

or

CDN

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

Register the plugin

Vue

//main.js

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

Vue.use(VWave)

or

Nuxt

// nuxt.config.js

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

Usage

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

Options

Usage with options

Global options

Vue

// main.js
 . . .

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

or

Nuxt

// nuxt.config.js

export default {
    modules: ['v-wave/nuxt'],

    vWave: {
        color: 'red',
        startingOpacity: 0.5,
        easing: 'ease-in',
    }
}

Per-directive options

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

Summary

Name Type Default
color string "currentColor"
initialOpacity number 0.2
finialOpacity number 0.1
duration number 0.4
easing string ease-out
cancellationPeriod number 75

Details

color

  • type: string

  • default: "currentColor"

    The background-color of the wave.

initialOpacity

  • type: number

  • default: 0.2

    The opacity of the wave when it first appears.

finalOpacity

  • type: number

  • default: 0.1

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

duration

  • type: number

  • default: 0.4

    The duration of the wave animation in seconds.

easing

  • type: string

  • default: "ease-out"

    Any valid CSS <timing-function>

cancellationPeriod

  • type: number

  • default: 75

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

    Note:
    The wave will not appear until after the delay, meaning a delay greater than 100ms can make the site feel sluggish.

Advanced

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

GitHub