HapticRipple Overview

HapticRipple is a lightweight JavaScript library for creating customizable ripple effects on UI elements - similar to the material design ripple effect but with more customization options. It enhances tactile feedback for clicks and touches on interactive elements.

Live Demo

Installation Options

1. npm/yarn:

   npm install haptic-ripple

   or

   yarn add haptic-ripple

2. CDN (for direct browser usage):

   <script src="https://cdn.jsdelivr.net/npm/haptic-ripple/dist/index.umd.js"></script>

3. Local download: Download the UMD build and include it in your project.

Basic Usage

When using with bundlers:

import { createHapticRipple } from "haptic-ripple";

const ripple = createHapticRipple();
ripple.enable("button"); // Apply to all buttons

When using via CDN or local UMD file:

// Access through the HapticRipple namespace
const ripple = HapticRipple.createHapticRipple({
    color: "rgba(255, 255, 255, 0.7)",
    size: 20,
    duration: 400,
});

ripple.enable("#my-button");

Features

• 🎨 Fully customizable (color, size, duration, opacity, scale, easing)
• 📱 Mobile-first design with touch event support
• 🧩 Simple API with both class and factory function approaches
• 🪄 Multiple independent instances supported
• 🌈 CSS variable integration for theming

Configuration Options

You can customize the ripple effect with these parameters:

| Property | Type | Default | Description | | -------------- | ------ | -------------- | ---------------------------------------- | | color | string | "rgb(0, 0, 0)" | CSS color value (supports CSS variables) | | size | number | 16 | Initial ripple diameter in pixels | | duration | number | 300 | Animation duration in milliseconds | | initialOpacity | number | 0.3 | Starting opacity (0-1) | | scale | number | 4 | Growth multiplier during animation | | easing | string | "ease-out" | CSS animation timing function |

Common Use Cases

1. Basic buttons:

   const buttonRipple = createHapticRipple({
       color: "rgba(255, 255, 255, 0.7)",
       size: 20,
   });
   
   buttonRipple.enable(".my-button");

2. Larger UI elements (cards, panels):

   // Avoid extreme combinations
   createHapticRipple({
       size: 8, // Too small
       scale: 100, // Excessive scaling
   });

   const cardRippleEffect = createHapticRipple({
       color: "rgba(0, 0, 200, 0.3)",
       size: 600,
       duration: 500,
       initialOpacity: 0.125,
       scale: 3,
   });
   
   cardRippleEffect.enable(".card-container");

   For larger UI elements like cards or panels, slower animations with larger initial sizes prevents the animation from appearing too aggressive or abrupt.

3. Using CSS variables for theming:

   :root {
       --primary-ripple-color: rgba(76, 110, 245, 0.7);
       --danger-ripple-color: rgba(250, 82, 82, 0.5);
   }

   createHapticRipple({
       color: "var(--primary-ripple-color)",
   }).enable(".primary-action");

4. Dynamically updating properties:

   const adaptiveRipple = createHapticRipple();
   
   // Update properties later
   adaptiveRipple.update({
       color: "#ff000080",
       duration: 500,
       scale: 6,
   });

API Reference

createHapticRipple(options?)

Factory function returns controller object:

function createHapticRipple(options?: HapticRippleOptions): {
    enable: (selector: string | HTMLElement | HTMLElement[]) => void;
    disable: (selector: string | HTMLElement | HTMLElement[]) => void;
    update: (newOptions: HapticRippleOptions) => void;
};

Class API

import { HapticRipple } from "haptic-ripple";

const ripple = new HapticRipple(options);
ripple.enable(".elements");
ripple.updateOptions(newOptions);
ripple.disable("#specific-element");

Troubleshooting

Ripple Not Visible?

• Check z-index conflicts
• Verify parent has position: relative
• Ensure no overflow:hidden is obscuring the effect
• Confirm element isn't disabled

Mobile Issues

/* Add to interactive elements */
touch-action: manipulation;

Browser Support

Works in all modern browsers

License

MIT License