custcur

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

Installation

Via CDN

<script src="https://unpkg.com/custcur@0.2.4/dist/bundle.js"></script>

Via Yarn or NPM

Install in terminal:

yarn add custcur
npm i custcur

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.

felixgro / custcur