🦄 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