Cursor

A customizable custom cursor component with smooth animations and hover interactions. Supports dynamic appearance changes and enhanced user interaction.

Example

Explore a live example in CodePen:

Props

Static Props

Static properties are set during initialization and cannot be modified later.

Name	Description	Type	Default Value
container	The container where the custom cursor is active. Use window for full-window activation.	Element | window	window
hideNative	Hides the native cursor if set to true.	boolean	false

Mutable Props

Mutable properties can be updated at runtime using .updateProps().

Name	Description	Type	Default Value
enabled	Enables or disables the custom cursor interactions.	boolean	true
width	The initial width of the custom cursor.	number	50
height	The initial height of the custom cursor.	number	50
lerp	Linear interpolation factor for smooth cursor movement. The value must be between 0 and 1, with higher values indicating faster movement.	number	0.2
autoStop	Stops rendering the cursor automatically when its coordinates and size closely match the target values.	boolean	true

Accessors

note

All Module's accessors are available in this class.

container

Type: Element | Window

The cursor container

coords

Type: { height: number; width: number; x: number; y: number; }

The current coordinates. These are updated during cursor movement.

domContainer

Type: HTMLElement

Returns the DOM parent for the cursor element.

hoveredElement

Type: undefined | ICursorHoveredElement

Stores information about the currently hovered element, including dimensions and interactive properties.

ICursorHoveredElement Structure

interface ICursorHoveredElement {
  element: Element;
  width?: number | "auto" | null;
  height?: number | "auto" | null;
  padding?: number;
  sticky?: boolean;
}

• element: The DOM element currently being hovered.
• width: Custom width for the cursor when hovering over this element (number, "auto", or null).
• height: Custom height for the cursor when hovering over this element (number, "auto", or null).
• padding: Additional padding around the cursor.
• sticky: Whether the cursor remains centered on the element.

inner

Type: HTMLElement

The inner element of the custom cursor, allowing additional styling.

outer

Type: HTMLElement

The outer element representing the visual cursor.

prefix

Type: string

Classname prefix for styling elements.

targetCoords

Type: { height: number; width: number; x: number; y: number }

Target coordinates of the cursor (without smooth interpolation).

Methods

note

All Module's methods are available in this class.

attachCursor

Registers a cursor type.

instance.attachCursor({
  element: document.getElementById('curor-type'),
  type: 'some_type',
});

attachElement

Registers an element to interact with the cursor, enabling dynamic size and position changes based on hover effects.

const hoveredElement = instance.attachElement({
  element: document.getElementById('hover-element'),
  type: 'some_type',
  width: 'auto',
  height: 'auto',
  padding: 10,
  sticky: true,
});

// Remove interaction
hoveredElement();

render

Manually triggers a cursor render.

canvas.render();

updateProps

Dynamically updates instance properties.

instance.updateProps({
  width: 100,
  height: 100,
});

destroy

Destroys the instance and cleans up resources.

canvas.destroy();

Callbacks

note

All Module's callbacks are available in this class.

render

Triggered on each render to update the cursor's position.

const destruct = instance.on('render', () => console.log('Cursor rendered'));

// Cancel the callback
destruct();