Skip to main content

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.

container​

  • Type: Element | window
  • Default: window
  • The container where the custom cursor is active.
    Use window for full-window activation.

hideNative​

  • Type: boolean
  • Default: false
  • Hides the native cursor if set to true.

Mutable Props​

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

enabled​

  • Type: boolean
  • Default: true
  • Enables or disables the custom cursor interactions.

width​

  • Type: number
  • Default: 50
  • The initial width of the custom cursor.

height​

  • Type: number
  • Default: 50
  • The initial height of the custom cursor.

lerp​

  • Type: number
  • Default: 0.2
  • Linear interpolation factor for smooth cursor movement. The value must be between 0 and 1, with higher values indicating faster movement.

autoStop​

  • Type: boolean
  • Default: true
  • Stops rendering the cursor automatically when its coordinates and size closely match the target values.

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();