@xpecta/vue-ripple

A lightweight Vue 3 library for adding material-design inspired ripple effects to your Vue components. Allows customization and target handling to fit most use cases.

Installation

# npm
npm install @xpecta/vue-ripple

Usage

Global Registration

Register the styles globally in your Vue application:

import "@xpecta/vue-ripple/style.css"; // Import the styles

Local Import

Import and use the component locally.

<template>
    <div
        class="my-button"
        @pointerdown="handlePointerDown"
        ref="buttonRef"
    >
        Click me
        <Ripple ref="rippleRef" />
    </div>
</template>

<script setup>
import { Ripple } from "@xpecta/vue-ripple";
import { ref } from "vue";

const ripple = useTemplateRef < InstanceType < typeof Ripple >> "ripple";

const handlePointerDown = (event) => {
    // Call the drop method on ripple with the client coordinates to cause some ripples.
    ripple.value.drop({
        x: event.clientX,
        y: event.clientY,
    });
};
</script>

<style>
.my-button {
    position: relative; /* Important: parent element must have position relative */
}
</style>

Props

| Prop | Type | Default | Description | | ---------- | ------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | | color | String | 'rgba(0, 0, 0, 0.5)' | The color of the ripple effect. You can use any valid CSS color or CSS variable (prefixed with --) | | disabled | Boolean | false | Whether to disable the ripple effect | | stretch | Boolean | false | Whether to stretch the ripple to the parent container | | diameter | Number | 100 | The ripple diameter if not stretched | | duration | Number | 300 | The ripple duration in ms |

Customizing Styles

The following CSS classes are used by the ripple component and can be overridden to customize the appearance:

• .ripple-wrapper: The wrapper for the ripple effect. Controls overflow.
• .ripple: The animated ripple element itself.

You can override these classes in your own stylesheet to change the effect's look and feel. For example:

.ripple-wrapper {
}

.ripple {
    background-color: rgba(255, 0, 0, 0.5);
    animation-duration: 300ms;
}

Browser Support

This library uses modern web APIs and is designed for Vue 3. It should work in all modern browsers that support Vue 3.

License

MIT