{"id":14300,"library":"vue-ripple-directive","title":"Vue Material Ripple Effect Directive","description":"vue-ripple-directive is a lightweight Vue.js directive that implements the Material Design ripple effect on any HTML element. Currently stable at version 2.0.1, the package provides a focused solution for adding interactive visual feedback to user interface elements, differentiating itself from larger component libraries by offering only the ripple functionality. Releases have historically addressed bug fixes and introduced features like custom colors and event modifiers, though recent development pace appears moderate. A key characteristic is its reliance on the host element having `position: relative` for accurate ripple positioning, a behavior that was explicitly enforced as a breaking change in version 2.0.1. It can be configured globally for default colors and z-index.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/PygmySlowLoris/vue-ripple-directive","tags":["javascript","vue","ripple","material","directive","ripple effect","button"],"install":[{"cmd":"npm install vue-ripple-directive","lang":"bash","label":"npm"},{"cmd":"yarn add vue-ripple-directive","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-ripple-directive","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for registering and utilizing the directive within a Vue application.","package":"vue","optional":false}],"imports":[{"note":"For Vue 3, register globally using `app.directive('ripple', Ripple)`. For Vue 2, use `Vue.directive('ripple', Ripple)`.","wrong":"const Ripple = require('vue-ripple-directive');","symbol":"Ripple","correct":"import Ripple from 'vue-ripple-directive';"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport Ripple from 'vue-ripple-directive';\n\nconst app = createApp(App);\n\n// Optional: Global configuration for all ripples\nRipple.color = 'rgba(100, 100, 255, 0.3)'; // Default blueish ripple color\nRipple.zIndex = 999; // Default z-index for ripple elements\n\n// Register the directive globally\napp.directive('ripple', Ripple);\n\napp.mount('#app');\n\n/* In App.vue or any Vue component template: */\n/*\n<template>\n  <div id=\"app\">\n    <h2>Click for a ripple effect!</h2>\n    <div v-ripple class=\"my-button default-ripple\">\n      Default Ripple\n    </div>\n    <div v-ripple=\"'rgba(255, 0, 0, 0.4)'\" class=\"my-button red-ripple\">\n      Red Ripple (Custom Color)\n    </div>\n    <div v-ripple.mouseover.1000 class=\"my-button hover-ripple\">\n      Hover Ripple (Custom Event & Speed)\n    </div>\n    <p>\n      This paragraph also has a ripple, but it might not look right\n      if its position is not relative!\n      <span v-ripple class=\"inline-ripple\">Click here</span>\n    </p>\n  </div>\n</template>\n\n<script>\nexport default {\n  name: 'App',\n};\n</script>\n\n<style>\n/* CRUCIAL: Elements with v-ripple MUST have position: relative */\n.my-button,\n.inline-ripple {\n  position: relative;\n  overflow: hidden; /* Ensures the ripple is clipped within bounds */\n  background-color: #4CAF50;\n  color: white;\n  padding: 15px 30px;\n  margin: 10px;\n  border-radius: 5px;\n  cursor: pointer;\n  display: inline-block;\n}\n.red-ripple {\n  background-color: #f44336;\n}\n.hover-ripple {\n  background-color: #2196F3;\n}\n.inline-ripple {\n  background-color: #ffeb3b;\n  color: #333;\n  padding: 5px 10px;\n}\n#app {\n  font-family: Avenir, Helvetica, Arial, sans-serif;\n  -webkit-font-smoothing: antialiased;\n  -moz-osx-font-smoothing: grayscale;\n  text-align: center;\n  color: #2c3e50;\n  margin-top: 60px;\n}\n</style>\n*/","lang":"javascript","description":"This quickstart demonstrates how to import, globally configure, and register the `v-ripple` directive in a Vue 3 application. It then shows its usage in a template with default behavior, a custom color parameter, and event/transition modifiers, emphasizing the essential `position: relative` CSS requirement."},"warnings":[{"fix":"Explicitly add `position: relative;` to the CSS rules for all elements that use `v-ripple`. Also, ensure `overflow: hidden;` is applied to clip the ripple within the element's bounds.","message":"Since version 2.0.1, the element to which the `v-ripple` directive is attached *must* have `position: relative` in its CSS for the ripple effect to position correctly. While the directive attempts to temporarily set `position: relative` if missing, this can lead to unpredictable layout shifts or visual glitches, especially when elements are dynamically moved or resized.","severity":"breaking","affected_versions":">=2.0.1"},{"fix":"Ensure you are using a recent version of the directive (2.0.x recommended). If targeting older browsers or environments, ensure your project's build pipeline (e.g., Babel) is correctly transpiling node_modules or specifically `vue-ripple-directive`.","message":"Older versions of `vue-ripple-directive` (prior to 1.0.9 and 1.0.7) had issues with ES6 syntax not being properly transpiled, leading to compatibility problems in environments that did not support newer JavaScript features natively or had incorrect build configurations.","severity":"gotcha","affected_versions":"<1.0.9"}],"env_vars":null,"search_vec":"'2.0.1':30,108 'accur':93 'ad':38 'address':61 'appear':77 'behavior':97 'break':104 'bug':62 'button':128 'chang':105 'characterist':81 'color':69,116 'compon':50 'configur':112 'current':26 'custom':68 'default':115 'design':19 'develop':75 'differenti':46 'direct':5,9,14,125 'effect':4,21,127 'element':25,45,88 'enforc':101 'event':71 'explicit':100 'featur':66 'feedback':41 'fix':63 'focus':35 'function':57 'global':113 'histor':60 'host':87 'html':24 'implement':16 'index':120 'interact':39 'interfac':44 'introduc':65 'javascript':121 'key':80 'larger':49 'librari':51 'lightweight':12 'like':67 'materi':2,18,124 'moder':78 'modifi':72 'offer':53 'pace':76 'packag':32 'posit':90,95 'provid':33 'recent':74 'relat':91 'releas':58 'relianc':84 'rippl':3,8,20,56,94,123,126 'solut':36 'stabl':27 'though':73 'user':43 'version':29,107 'visual':40 'vue':1,7,122 'vue-ripple-direct':6 'vue.js':13 'z':119 'z-index':118","created_at":"2026-04-20T01:58:59.658416+00:00","updated_at":"2026-04-20T01:58:59.658416+00:00","problems":[{"fix":"Add `position: relative;` and `overflow: hidden;` to the CSS class or style attribute of the element where `v-ripple` is used.","cause":"The element applying the `v-ripple` directive does not have `position: relative` and/or `overflow: hidden` in its CSS.","error":"Ripple effect appears incorrectly positioned, extends beyond element boundaries, or is invisible."},{"fix":"For Vue 3, ensure you `import { createApp } from 'vue'` and use `app.directive('ripple', Ripple)`. For Vue 2, ensure `import Vue from 'vue'` and use `Vue.directive('ripple', Ripple)`.","cause":"Vue instance (or `app` in Vue 3) is not correctly imported, globally available, or the directive registration syntax is incorrect for the Vue version being used.","error":"`Vue is not defined` or `app.directive is not a function` when registering the directive."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/PygmySlowLoris/vue-ripple-directive","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vue-ripple-directive","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}