Repository files navigation

This is a tiny JavaScript package that creates custom cursor for you withminimal JavaScript and allows you to write hover effects for the cursor(s) inCSS.

• 🪶 Lightweight (< 1kb minified)
• 🎨 Fully customizable with CSS
• ⚡ Simple API with minimal configuration
• 🔄 Multiple cursor support for follow-along effects
• 🎯 Target specific elements for custom hover states
• 📱 Works with mouse and touch devices

Perfect for creative websites, portfolios, and interactive experiences where youwant to replace the default cursor with something more engaging.

For this package to work with a CDN, you'll need to access theCursor classfrom thewindow object.

<scriptdefersrc="https://unpkg.com/custom-cursor@latest/dist/cdn.min.js"></script><script>document.addEventListener('DOMContentLoaded',()=>{newwindow['Cursor']({})})</script>

When using the CDN version, you still have full access to all configurationoptions:

document.addEventListener('DOMContentLoaded',()=>{newwindow['Cursor']({count:3,// Creates multiple cursor elementstargets:['a','button','.interactive'],// Elements that trigger hover states})})

These options work exactly the same way as in the package version, giving youcomplete control over your custom cursor behavior.

yarn add -D custom-cursornpm install -D custom-cursor

importCursorfrom'custom-cursor'newCursor({})

TheCursor constructor accepts an optional configuration object with twoparameters:

newCursor({count:5,// Creates multiple cursor elementstargets:['a','.title','#header'],// Elements that trigger hover states})

Both parameters are optional and can be customized to fit your specificrequirements.

This parameter lets you specify the number of cursor elements to create, whichis ideal for creating trailing cursor effects.

When you setcount: 5, the package generates the following HTML structure:

<divdata-cursor="0"style="..."></div><divdata-cursor="1"style="..."></div><divdata-cursor="2"style="..."></div><divdata-cursor="3"style="..."></div><divdata-cursor="4"style="..."></div>

Each cursor element receives adata-cursor attribute with its index number,allowing you to style each cursor element individually with CSS:

[data-cursor] {width:20px;height:20px;}[data-cursor='0'] {background:#00f;}[data-cursor='1'] {background:#eee;}

This approach gives you complete control over the appearance of each cursor inthe sequence, creating trailing effects, size variations, or color gradients.

Thetargets parameter lets you define specific HTML elements that will triggercursor hover effects.

For example, withtargets: ['a', '.title', '#header'], the package will:

1. Locate all<a> elements, elements with the class.title, and the elementwith ID#header
2. Add event listeners formouseover andmouseleave on these elements
3. When the mouse hovers over a target, add a class ofcursor-hover--<target>to the document body

The<target> portion of the class name corresponds to the identifier in yourtargets array. For instance, hovering over.title elements will addcursor-hover--title to the body.

You can style cursor hover states using the added class names. For example:

/* Style all cursors when hovering over links */.cursor-hover--a [data-cursor] {}/* Style all cursors when hovering over elements with .title class */.cursor-hover--title [data-cursor] {}/* Style all cursors when hovering over element with #header ID */.cursor-hover--header [data-cursor] {}/* Style specific cursors by index during hover */.cursor-hover--header [data-cursor='0'] {}.cursor-hover--header [data-cursor='1'] {}

This approach gives you fine-grained control over cursor appearance duringdifferent hover interactions.