🦄 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://cursorjs.netlify.app

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

# Run dev server
npm run dev

# Generate UMD and module version
npm run prod

# Build production site
npm run build

# Generate UMD and module version then publish NPM package
npm run publish

License

MIT License

Copyright (c) 2023 @phucbm