Class Cursor

Custom cursor with smooth motion, hover sizing, sticky elements, and typed variants.

Builds outer/inner DOM (optional) and hides the native cursor when configured
Interpolates position/size via Raf; optional SVG path trailing (behavior: 'path')
Hover targets via attachHover; alternate visuals via attachCursor

Documentation

Hierarchy (View Summary)

Module<TC, TS, TM>
- Cursor

Index

Constructors

constructor

new Cursor(
    props?: TModuleProps<
        ICursorCallbacksMap,
        ICursorStaticProps,
        ICursorMutableProps,
        Cursor,
    >,
): Cursor
Parameters
- Optionalprops: TModuleProps<
      ICursorCallbacksMap,
      ICursorStaticProps,
      ICursorMutableProps,
      Cursor,
  >
Returns Cursor
Overrides Module.constructor
- Defined in src/components/Cursor/index.ts:76

Accessors

callbacks

get callbacks(): Callbacks<CallbacksMap, this>
Retrieves the module's callbacks instance.

Returns Callbacks<CallbacksMap, this>
Inherited from Module.callbacks
- Defined in src/base/Module/index.ts:64

container

get container(): Element | Window
Returns Element | Window
- Defined in src/components/Cursor/index.ts:112

coords

get coords(): {
    angle: number;
    height: number;
    velocity: number;
    width: number;
    x: number;
    y: number;
}
Smoothed coordinates including width/height.

Returns {
    angle: number;
    height: number;
    velocity: number;
    width: number;
    x: number;
    y: number;
}
- Defined in src/components/Cursor/index.ts:147

domContainer

get domContainer(): HTMLElement
DOM parent for the cursor node (body when container is window).

Returns HTMLElement
- Defined in src/components/Cursor/index.ts:117

hoveredElement

get hoveredElement(): undefined | CursorHoverElement
Topmost active hover target, if any.

Returns undefined | CursorHoverElement
- Defined in src/components/Cursor/index.ts:182

initialHeight

get initialHeight(): number
Returns number
- Defined in src/components/Cursor/index.ts:142

initialWidth

get initialWidth(): number
Returns number
- Defined in src/components/Cursor/index.ts:138

inner

get inner(): HTMLElement
Returns HTMLElement
- Defined in src/components/Cursor/index.ts:129

isDestroyed

get isDestroyed(): boolean
Indicates whether the instance has been destroyed.

After destruction, destroy is a no-op.

Returns boolean
Inherited from Module.isDestroyed
- Defined in src/internal/Destroyable/index.ts:24

name

get name(): string
The name of the module, derived from the class name

Returns string
Inherited from Module.name
- Defined in src/base/Module/index.ts:57

outer

get outer(): HTMLElement
Returns HTMLElement
- Defined in src/components/Cursor/index.ts:125

path

get path(): SVGPathElement
SVG path element for path behavior (not necessarily mounted).

Returns SVGPathElement
- Defined in src/components/Cursor/index.ts:134

prefix

get prefix(): string
Optional prefix for classnames used by the module

Returns string
Overrides Module.prefix
- Defined in src/components/Cursor/index.ts:108

props

get props(): TRequiredProps<MutableProps & StaticProps>
Current properties. Do not mutate these directly, use updateProps instead.

Returns TRequiredProps<MutableProps & StaticProps>
Inherited from Module.props
- Defined in src/base/Module/index.ts:47

targetCoords

get targetCoords(): ICursorFullCoords
Target coordinates (hover dimensions applied, no smoothing).

Returns ICursorFullCoords
- Defined in src/components/Cursor/index.ts:156

Methods

`Protected`_addTempClassName

_addTempClassName(element: Element, ...classes: string[]): void
Adds prefixed classes to an element and removes them on destroy.

Skips classes that are already present on the element.
Parameters
- element: Element
  Target DOM element.
- ...classes: string[]
  Unprefixed class name segments.
Returns void
Inherited from Module._addTempClassName
- Defined in src/base/Module/index.ts:139

`Protected`_cn

_cn(...classes: string[]): string
Builds one or more prefixed class names.
Parameters
- ...classes: string[]
  Unprefixed class name segments.
Returns string
Space-separated prefixed class string.
Inherited from Module._cn
- Defined in src/base/Module/index.ts:127

`Protected`_destroy

_destroy(): void
Internal method to handle the destruction of the module. It removes all callbacks, destroys properties, and cleans up event listeners and class names.

Returns void
Inherited from Module._destroy
- Defined in src/base/Module/index.ts:202

`Protected`_emit

_emit<E extends keyof ICursorCallbacksMap>(
event: E,
arg: ICursorCallbacksMap[E],
): void
Emits a callback event with a fixed payload.
Type Parameters
- E extends keyof ICursorCallbacksMap
Parameters
- event: E
- arg: ICursorCallbacksMap[E]
Returns void
Inherited from Module._emit
- Defined in src/base/Module/index.ts:107

_getMutable

_getMutable(): {
    __mutableProp: true;
    autoStop: boolean;
    enabled: boolean;
    height: string
    | number;
    lerp: number;
    width: string | number;
}
Set default mutable props

Returns {
    __mutableProp: true;
    autoStop: boolean;
    enabled: boolean;
    height: string | number;
    lerp: number;
    width: string | number;
}
- __mutableProp: true
- autoStop: boolean
  Stops rendering the cursor automatically when its coordinates and size closely match the target values.
  Default
  true
- enabled: boolean
  Enables or disables the custom cursor interactions.
  Default
  true
- height: string | number
  The initial height of the custom cursor. Supports css units like px, rem, vw, vh, svh.
  Default
  50
- lerp: number
  Linear interpolation factor for smooth cursor movement. The value must be between 0 and 1, with higher values indicating faster movement.
  Default
  0.2
- width: string | number
  The initial width of the custom cursor. Supports css units like px, rem, vw, vh, svh.
  Default
  50
Overrides Module._getMutable
- Defined in src/components/Cursor/index.ts:49

_getStatic

_getStatic(): {
    __staticProp: true;
    append: boolean;
    behavior: "path"
    | "default";
    container: Element | Window;
    hideNative: boolean;
    transformModifier: (coords: ICursorFullCoords) => string;
}
Get default static props

Returns {
    __staticProp: true;
    append: boolean;
    behavior: "path" | "default";
    container: Element | Window;
    hideNative: boolean;
    transformModifier: (coords: ICursorFullCoords) => string;
}
- __staticProp: true
- append: boolean
  Appends the custom cursor to the container. Use false if you need only cursor logic and interactions.
  Default
  true
- behavior: "path" | "default"
  Cursor behavior
  Default
  'default'
- container: Element | Window
  The container where the custom cursor is active. Use window for full-window activation.
  Default
  window
- hideNative: boolean
  Hides the native cursor if set to true.
  Default
  false
- transformModifier: (coords: ICursorFullCoords) => string
  Modifier for the cursor transform.
  
  Default
  (coords) => translate(${coords.x}px, ${coords.y}px)
Overrides Module._getStatic
- Defined in src/components/Cursor/index.ts:45

`Protected`_handleProps

_handleProps(props: Partial<ICursorMutableProps>): void
Method that is called when the module's properties mutate. In most cases, used to handle callbacks.
Parameters
- props: Partial<ICursorMutableProps>
Returns void
Overrides Module._handleProps
- Defined in src/components/Cursor/index.ts:188

attachCursor

attachCursor(__namedParameters: ICursorType): void
Registers a typed cursor element and appends it to inner.
Parameters
- __namedParameters: ICursorType
Returns void
- Defined in src/components/Cursor/index.ts:317

attachHover

attachHover(settings: ICursorHoverElementProps): () => void
Registers a hover target that can resize, snap, or sticky-move the cursor.
Parameters
- settings: ICursorHoverElementProps
Returns () => void
Destructor that detaches listeners for this target
- Defined in src/components/Cursor/index.ts:267

destroy

destroy(): void
Destroys the instance and runs all registered cleanup actions.

Safe to call multiple times; subsequent calls are ignored.

Execution order:
1. _destroy
2. all onDestroy callbacks, in registration order
3. isDestroyed is set to true
Returns void
Inherited from Module.destroy
- Defined in src/internal/Destroyable/index.ts:46

on

on<T extends keyof ICursorCallbacksMap>(
    target: T,
    listener: TCallbacksAction<ICursorCallbacksMap[T], Cursor>,
    settings?: ICallbacksSettings,
): () => void
Adds a custom callback to the module.
Type Parameters
- T extends keyof ICursorCallbacksMap
Parameters
- target: T
  The event type to listen for (e.g., 'props', 'destroy').
- listener: TCallbacksAction<ICursorCallbacksMap[T], Cursor>
  The function to execute when the event is triggered.
- settings: ICallbacksSettings = {}
  Additional settings for the callback.
Returns () => void
Inherited from Module.on
- Defined in src/base/Module/index.ts:190

onDestroy

onDestroy(action: () => void): void
Registers a function to run when the instance is destroyed.

If the instance is already destroyed, action runs immediately.
Parameters
- action: () => void
  Cleanup function (for example remove listeners or DOM classes).
Returns void
Inherited from Module.onDestroy
- Defined in src/internal/Destroyable/index.ts:64

render

render(): void
Advances interpolation and writes transforms.

Returns void
- Defined in src/components/Cursor/index.ts:342

updateProps

updateProps(props: Partial<ICursorMutableProps>): void
Change module's mutable properties
Parameters
- props: Partial<ICursorMutableProps>
Returns void
Inherited from Module.updateProps
- Defined in src/base/Module/index.ts:157

Class Cursor

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Cursor

Accessors

callbacks

Returns Callbacks<CallbacksMap, this>

container

Returns Element | Window

coords

Returns { angle: number; height: number; velocity: number; width: number; x: number; y: number;}

domContainer

Returns HTMLElement

hoveredElement

Returns undefined | CursorHoverElement

initialHeight

Returns number

initialWidth

Returns number

inner

Returns HTMLElement

isDestroyed

Returns boolean

name

Returns string

outer

Returns HTMLElement

path

Returns SVGPathElement

prefix

Returns string

props

Returns TRequiredProps<MutableProps & StaticProps>

targetCoords

Returns ICursorFullCoords

Methods

Protected_addTempClassName

Parameters

Returns void

Protected_cn

Parameters

Returns string

Protected_destroy

Returns void

Protected_emit

Type Parameters

Parameters

Returns void

_getMutable

Returns { __mutableProp: true; autoStop: boolean; enabled: boolean; height: string | number; lerp: number; width: string | number;}

__mutableProp: true

autoStop: boolean

Default

enabled: boolean

Default

height: string | number

Default

lerp: number

Default

width: string | number

Default

_getStatic

Returns { __staticProp: true; append: boolean; behavior: "path" | "default"; container: Element | Window; hideNative: boolean; transformModifier: (coords: ICursorFullCoords) => string;}

__staticProp: true

append: boolean

Default

behavior: "path" | "default"

Default

container: Element | Window

Default

hideNative: boolean

Default

transformModifier: (coords: ICursorFullCoords) => string

Default

Returns {
angle: number;
height: number;
velocity: number;
width: number;
x: number;
y: number;
}

`Protected`_addTempClassName

`Protected`_cn

`Protected`_destroy

`Protected`_emit

Returns {
__mutableProp: true;
autoStop: boolean;
enabled: boolean;
height: string | number;
lerp: number;
width: string | number;
}

Returns {
__staticProp: true;
append: boolean;
behavior: "path" | "default";
container: Element | Window;
hideNative: boolean;
transformModifier: (coords: ICursorFullCoords) => string;
}

`Protected`_handleProps