🦄 Cursor.js

Create custom mouse cursor with pure vanilla JS (4kb) and CSS (optional) with no dependency.

Key features:

• Cursor moving with easing (no dependencies)
• Extremely light-weight (4kb)
• One cursor - unlimited styles on hover

Demo 👉 https://phucbm.github.io/cursorjs/

Getting started

Installation

NPM Package

npm i @phucbm/cursorjs

Import

import "@phucbm/cursorjs";

Download

👉 Self hosted - Download the latest release

<script src="./cursorjs.min.js"></script>

👉 CDN Hosted - jsDelivr

<!-- JS (10KB) -->
<script src="https://cdn.jsdelivr.net/gh/phucbm/cursorjs@latest/dist/cursorjs.min.js"></script>

Initialize

// with default style
Cursorjs.create();

// with more options
Cursorjs.create({
    id: 'my-cursor',
    innerHTML: '<i class="icon-cursor"></i>',
    hover: [
        {
            selectors: '.items',
            className: 'my-style-class'
        },
    ]
});

Docs

Cursor options

Name	Type	Default	Description
id	string	"css-cursor-<uniqueID>"	Set ID to get instance
speed	float	0.2	Cursor easing speed, the smaller, the slower
container	DOM element	document.body	Where to append cursor HTML
className	string	""	Class for cursor
innerHTML	string	""	Inner HTML for cursor
classInViewport	string	""	Class when cursor is in viewport
matchMedia	string	"(hover:hover)"	Only init if match this media
hoverPrefixClass	string	""	Prefix for hover class.
hover	string	[]	Actions when hover on specific elements. See Hover object below.
wrapperCSS	CSS object	{...}	Default style for cursor wrapper (*)
cursorCSS	CSS object	{...}	Default style for cursor (*)

(*) default CSS

const options = {
    wrapperCSS: {
        pointerEvents: 'none',
        zIndex: '9999',
        position: 'fixed',
        top: 0,
        left: 0,
    },
    cursorCSS: {
        boxShadow: '0 0 0 2px rgba(0, 0, 0, .3)',
        width: '40px',
        height: '40px',
        borderRadius: '50%',
        transition: 'all .3s ease',
        position: 'absolute',
        transform: 'translate(-50%,-50%)'
    }
}

Hover object

Name	Type	Default	Description
selectors	string	""	CSS selector, multiple elements is supported
className	string	""	Add this class to cursor when hover on selectors
cursor	string	"none"	CSS cursor when hover on selectors

// sample hover array
const options = {
    hover: [
        {
            selectors: '.item-a, .item-b',
            className: 'is-hover-on-items',
            cursor: 'pointer',
        },
        {
            selectors: '.item-c',
            className: 'is-hover-on-item-c',
            cursor: 'none',
        }
    ]
}

Methods

const cursor = Cursorjs.get('my-cursor');

// remove cursor from DOM
cursor.destroy();

// check new hover selectors, useful when new items are loaded via AJAX
cursor.refresh();

Deployment

# Install dependencies
pnpm install

# Run dev server
pnpm dev

# Generate UMD and module version
pnpm prod

# Build production site
pnpm build

The demo site is deployed to GitHub Pages on every push to main.

Publish

Publishing to NPM is automated by publish-npm-action via OIDC trusted publishing. Create a GitHub release with a tag like v2.0.2: the workflow sets package.json to that version, builds dist/, commits both back to main and publishes the package.

License

MIT License

Copyright (c) 2023 @phucbm