Nuxt Ripple

Add simple ripple effects to your elements with customizable settings.

✨ Release Notes

Quick Setup

1. Add nuxt-ripple dependency to your project.

pnpm add nuxt-ripple

2. Add nuxt-ripple to the modules section of nuxt.config.ts.

export default defineNuxtConfig({
  modules: [
    'nuxt-ripple'
  ]
})

Simple Usage

Use the v-ripple directive on any element where you want to apply the ripple effect.

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

Configuration

If you want to modify the default global settings for all your ripple effects, you can set it in the ripple app options property in your nuxt.config.ts file.

export default defineNuxtConfig({
  // Set the default global settings for all your ripple effects
  ripple: {
    mode: 'click',
    color: 'rgba(255, 255, 255, 0.4)',
    duration: 350,
    scale: 1,
    overflow: false,
    pulseInterval: 1000 // -> Requires 'pulse' mode to be enabled for it to take effect
  },
})

Available options

Argument	Type	Description	Required
`mode`	`'click'`, `'hover'` or `'pulse'`	Ripple mode.	❌
`color`	`string`	Ripple color. Accepts HEX, RGB, or RGBA Values. Use RGBA with low opacity to create a transparent ripple effect.	❌
`duration`	`number`	Ripple propagation duration in miliseconds.	❌
`overflow`	`boolean`	Ripple overflow. If false the ripple will not propagate outside the element; otherwise, it will.	❌
`scale`	`number`	Ripple scale.	❌
`pulseInterval`	`number`	Ripple pulse interval speed in miliseonds. Require `'pulse'` mode enabled.	❌

Override global settings for a specific element

If you want to override the default global settings for a specific element, you can pass an object with the desired options to the v-ripple directive.

<!-- Overrides the mode to 'hover' for this specific element -->
<button v-ripple="{ mode: 'hover' }">Click me!</button>

Utils

You can dynamically update the default global settings using useRipple().updateRippleConfig({ ...options }) passing the options you want to update.

<script setup>
const { updateRippleConfig } = useRipple()

updateRippleConfig({ mode: 'hover', overflow: true })
</script>

As an extra, you can get all the global settings as readonly reactive objects

<script setup>
const { color, mode, duration, overflow, scale, pulseInterval } = useRipple()
// color.value
// ...
</script>

<template>
  <main>{{ color }}</main>
</template>