bouncy-cursor
v3.0.7
Published
A lightweight JavaScript module that replaces the default system cursor with a custom pointer image. The pointer smoothly follows your mouse or touch movements and features a satisfying bouncy animation every time you click. Perfect for adding interactive
Readme
Custom Cursor with Smooth Bouncy Click Animation
A lightweight JavaScript module that replaces the default system cursor with a custom pointer image. The pointer smoothly follows your mouse or touch movements and features a satisfying bouncy animation every time you click. Perfect for adding interactive and eye-catching UI effects to your website or app.
✨ Features
- Hide the default system cursor
- Custom image-based pointer that follows the mouse position
- Smooth scaling effect on click/touch
- Works with mouse and touch events
- Easy integration with HTML + Tailwind CSS or React/Next.js
📦 Installation
Install via NPM:
npm install bouncy-cursoror if you want to include manually, copy the browser.js or react.js files to your project.
🛠 Usage with HTML + Tailwind CSS
Step 1: Include Tailwind CDN in your <head>
<script src="https://cdn.tailwindcss.com"></script>Step 2: Add a placeholder div for the cursor
<div id="insertCursor"></div>Step 3: Import the module and attach cursor
<script type="module">
import { cursor, attachMouseEvents } from './dist/browser.js';
// Insert the custom cursor HTML
document.getElementById('insertCursor').innerHTML = cursor;
// Attach mouse and touch events globally
attachMouseEvents();
</script>✅ Full Example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Custom Cursor Example</title>
<script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-gray-100 flex items-center justify-center h-screen">
<h1 class="text-4xl font-bold">Hover around!</h1>
<div id="insertCursor"></div>
<script type="module">
import { cursor, attachBouncyCursor } from './dist/browser.js';
attachBouncyCursor();
</script>
</body>
</html>⚛ Usage with React / Next.js
Step 1: Import the React component
import BouncyClick from 'bouncy-cursor/react'; Step 2: Use the component in your app
function App() {
return (
<div>
<h1>Hello Custom Cursor!</h1>
<BouncyClick />
</div>
);
}
export default App;The component automatically attaches mouse and touch events globally using
useEffect(). The cursor will follow your mouse or touch anywhere on the page.
📄 Notes
- The
BouncyClickcomponent is designed for React projects only. - The
browser.jsversion works for plain HTML, CSS, and JS projects. - The default cursor image can be changed by passing the
imageprop (React) or replacing thesrcinbrowser.js. - The default size of the cursor is
w-12(Tailwind width class) but can be customized in React viasizeprop.