The material-ripple directive for Vue that actually works
The material-ripple directive for Vue that actually works
Also available for React: use-wave
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:
pointerdown
instead of pointerup
width
and height
.display: flex
).currentColor
).border-radius: 5px 20px 15px 30px
) perfectly fine.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.
$ npm i v-wave
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.config.js
// Nuxt 3
export default {
modules: ['v-wave/nuxt']
}
// Nuxt 2
export default {
modules: ['v-wave/nuxt/v2']
}
<script src="https://unpkg.com/v-wave"></script>
// With a CDN, `VWave` is made available as a global
Vue.use(VWave)
See: configuring globally, configuring locally
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.config.js
export default {
modules: ['v-wave/nuxt'],
vWave: {
color: 'red',
initialOpacity: 0.5,
easing: 'ease-in'
}
}
<button
v-wave="{
color: 'red',
initialOpacity: 0.5,
easing: 'ease-in',
}"
>
Click here
</button>
Name | Default | Type |
---|---|---|
color | "currentColor" |
string |
initialOpacity | 0.2 |
number |
finalOpacity | 0.1 |
number |
duration | 0.4 |
number |
dissolveDuration | 0.15 |
number |
easing | ease-out |
string |
cancellationPeriod | 75 |
number |
trigger | "auto" |
string | boolean | "auto" |
tagName | "div" |
string |
string
(background
shorthand syntax)"currentColor"
Sets the background of the ripple.
Supports any value that the CSSbackground
property does.
<button
v-wave="{
color: 'red',
}"
>
Click here
</button>
<button
v-wave="{
color: 'radial-gradient(closest-side, #fff, #00f, #fff)',
}"
>
Click here
</button>
<button
v-wave="{
color: 'no-repeat url(https://...) 0 0 / cover',
}"
>
Click here
</button>
number
0.2
The opacity of the ripple when it first appears.
See: initialOpacity: 1, initialOpacity: 0
<button
v-wave="{
initialOpacity: 1,
}"
>
Click here
</button>
<button
v-wave="{
initialOpacity: 0,
}"
>
Click here
</button>
number
0.1
The opacity the ripple should be when it has stopped moving.
See: finalOpacity: 1, finalOpacity: 0
<button
v-wave="{
finalOpacity: 1,
}"
>
Click here
</button>
<button
v-wave="{
finalOpacity: 0,
}"
>
Click here
</button>
number
(seconds)0.4
The duration of the ripple in seconds.
The total duration isduration + dissolveDuration
number
(seconds)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 isduration + dissolveDuration
<button
v-wave="{
dissolveDuration: 3,
}"
>
Click here
</button>
string
(<easing-function>
)"ease-out"
Any valid CSS
<easing-function>
(see more)
<button
v-wave="{
easing: 'cubic-bezier(0,.57,.89,0)',
}"
>
Click here
</button>
number
(milliseconds)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.
"auto" | string | boolean
"auto"
Sets the behavior of the wave when used with triggers. (See the dedication 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.
<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>
string
"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.
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.
If you need to temporarily disable the wave effect, simply pass false
to the directive.
Note that v-wave checks for strict
false
equality (=== false
).
Using any other falsely value will not disable the directive.
<button v-wave="false">Click me!</button>
<script>
import VWave from 'v-wave'
const { vWave, vWaveTrigger } = VWave.createLocalWaveDirective({
/* global options */
})
</script>
<template>
<button v-wave>Click me!</button>
</template>
<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>
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).
This project is distributed under the MIT License.
Copyright (c) 2021 Justin Taddei
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.