custcur

A lightweight, highly customizable cursor event framework for the web.

Installation

Via CDN

<script src="https://unpkg.com/[email protected]/dist/bundle.js"></script>

Via Yarn or NPM

1. Install in terminal:

yarn add custcur
npm i custcur

2. Initialize a custom cursor with default options:

import CustCur from 'custcur';

const cursor = new CustCur();

Usage

You can pass an options object as a parameter to the constructor in order to overwrite defaults:

const options = {
	target: document.querySelector('.section-1'),
	tag: 'div',
	classes: {
		base: 'cursor',
		hover: 'cursor-hover',
		click: 'cursor-click',
	},
};

const cursor = new CustCur(options);

You can also assign an existing html element as your custom cursor node:

const cursor = new CustCur({
	target: window,
	node: document.querySelector('.custom-cursor'),
});

The tag and classes.base parameters will get completely ignored if a node is present. Nevertheless the specified node will get the defined event classes when an related event occures within the defined target.

Available Options

| Property | Type | Description | Default | | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------- | | target | Node | Parent Element for custom cursor. | window | | node | Node? | Custom cursor node element. If not present, CusCur will create a node of the specified tag and assign the defined classname. | null | | hoverables | Array | Array of css-selectors or node elements within the specified target that should trigger the cursor's hover event. | ['a', 'button'] | | hideDefault | Boolean | Determine if the system's default cursor should be hidden when inside of specified target. | true | | classes.base | String | Specifies the cursor's base classname. | 'cc-cursor' | | classes.hover | String | Specifies a classname for the cursor's hover state. | 'cc-hover' | | classes.click | String | Specifies a classname for the cursor's click state. | 'cc-click' | | onEnter | Method | Listen for mouseover event on specified target. | (e)=>{} | | onLeave | Method | Listen for mouseout event on specified target. | (e)=>{} | | onMove | Method | Listen for mousemove event on specified target. | (e)=>{} | | onClick | Method | Listen for mousedown event within specified target. | (e)=>{} | | onClickRelease | Method | Listen for mouseup event within specified target. | (e)=>{} | | onHoverEnter | Method | Listen for mouseover event on all specified hoverables. | (e)=>{} | | onHoverLeave | Method | Listen for mouseout event on all specified hoverables. | (e)=>{} |

...? type can be null.

Available Methods

| Method | Description | | --------------------------- | ------------------------------------------------------------------------------- | | State | | | cursor.enable() | Enable custom cursor along with all event listeners. | | cursor.disable() | Disable custom cursor and remove all event listeners. | | cursor.toggle() | Toggle between enabled and disabled state. | | Events | | | cursor.onEnter(fn) | Register a callback function for mouseover event on specified target. | | cursor.onLeave(fn) | Register a callback function for mouseout event on specified target. | | cursor.onMove(fn) | Register a callback function for mousemove event on specified target. | | cursor.onClick(fn) | Register a callback function for mousedown event within specified target. | | cursor.onClickRelease(fn) | Register a callback function for mouseup event within specified target. | | cursor.onHoverEnter(fn) | Register a callback function for mouseover event on all specified hoverables. | | cursor.onHoverLeave(fn) | Register a callback function for mouseout event on all specified hoverables. |

Each event callback will overwrite it's related event method from the initial options object.