InteractiveCursor Component

The InteractiveCursor is a Svelte 5 component that provides a customizable, interactive cursor effect. It dynamically changes its position and size based on user interactions within specified trigger areas. This component is ideal for enhancing user experiences with visually engaging cursor animations.

Live Demo

CHANGELOG

---

Installation

# npm
npm install @lostisworld/svelte-interactive-cursor

# pnpm
pnpm add @lostisworld/svelte-interactive-cursor

---

Features

1. Dynamic Resizing: The cursor adjusts its size and position dynamically when hovering over elements specified in the useDataElementRect property.
2. Scaling on Interaction: Scale transformations can be applied to the cursor when hovering over specified elements using scaleOnActive.
3. Animation Control: Smooth animations with customizable duration and easing using the Web Animations API.
4. Custom Icons: Allows custom rendering inside the cursor element using the children snippet.
5. State Exposure: Exposes activeDataValue and isActive as bindable props to track cursor state in the parent.
6. Responsive Design: Automatically disables the interactive cursor below a configurable breakpoint or when reduced motion is preferred.
7. Reduced Motion: Dynamically responds to OS-level reduced motion changes mid-session — no page reload required.
8. Hide Native Cursor: Optionally hides the OS cursor inside trigger areas via hideNativeCursor.
9. Performance: Animations are throttled to one per frame via requestAnimationFrame, layout reads are cached, and the module is loaded only once across all instances.

---

Types

ScaleOnActiveElement

type ScaleOnActiveElement = {
	element: string; // The name of the element (value of `data-interactive-cursor`).
	scaleMultiplicator?: number; // Scale factor to apply when the element is active. Default: 3.
};

InteractiveCursorOptions

interface InteractiveCursorOptions {
	defaultSize?: number; // Default cursor size in pixels. Default: 32.
	scaleOnActive?: ScaleOnActiveElement[]; // Elements with scale factors. Default: [].
	duration?: number; // Animation duration in milliseconds. Default: 500.
	easing?: string; // CSS easing for the animation. Default: 'linear'.
	useDataElementRect?: string[]; // Elements that trigger cursor resizing. Default: [].
	hideNativeCursor?: boolean; // Hide the OS cursor inside trigger areas. Default: false.
}

---

Usage

Basic Setup

<script lang="ts">
	import InteractiveCursor from '@lostisworld/svelte-interactive-cursor';
</script>

<div data-interactive-cursor-area>
	<button data-interactive-cursor="btn">Hover me!</button>
</div>

<InteractiveCursor
	defaultSize={40}
	duration={300}
	scaleOnActive={[{ element: 'btn', scaleMultiplicator: 2 }]}
	useDataElementRect={['btn']}
/>

Advanced Example

<script lang="ts">
	import InteractiveCursor, {
		type ScaleOnActiveElement,
		type ActiveDataValue
	} from '@lostisworld/svelte-interactive-cursor';

	let currentCursorState: ActiveDataValue = $state({ activeDataName: '', activeDataElement: null });
	let cursorIsActive = $state(false);

	const scaleOnActive: ScaleOnActiveElement[] = [
		{ element: 'image' },
		{ element: 'video', scaleMultiplicator: 4 },
		{ element: 'link' },
		{ element: 'mixblend', scaleMultiplicator: 8 }
	];

	const customCursorProps = [
		{ data: 'image', icon: '<svg>...</svg>' },
		{ data: 'video', icon: '<svg>...</svg>', cursorClass: 'bg-red-500 text-white' },
		{ data: 'link', icon: '<svg>...</svg>', cursorClass: 'bg-sky-500 text-white' },
		{ data: 'tablist', cursorClass: 'rounded-none outline outline-2 outline-purple-500' }
	];
</script>

<section data-interactive-cursor-area>
	<div data-interactive-cursor="image">Image</div>
	<div data-interactive-cursor="video">Video</div>
	<div data-interactive-cursor="link">Link</div>
</section>

<InteractiveCursor
	bind:activeDataValue={currentCursorState}
	bind:isActive={cursorIsActive}
	{scaleOnActive}
	useDataElementRect={['tablist']}
	duration={400}
	easing="linear"
	breakpoint={1024}
	class="rounded-full flex items-center justify-center {currentCursorState.activeDataName === ''
		? 'bg-white text-black'
		: (customCursorProps.find((s) => s.data === currentCursorState.activeDataName)?.cursorClass ??
			'bg-white text-black')}"
>
	{#each customCursorProps as { icon, data }}
		{#if data === currentCursorState.activeDataName && icon}
			{@html icon}
		{/if}
	{/each}
</InteractiveCursor>

---

Component Props

Prop	Type	Default	Description
defaultSize	number	32	Default cursor size in pixels.
scaleOnActive	ScaleOnActiveElement[]	[]	Elements and their scale factors when hovered.
duration	number	500	Animation duration in milliseconds.
easing	string	'linear'	CSS easing function for the animation (e.g. 'ease-out', 'cubic-bezier(0.4,0,0.2,1)').
useDataElementRect	string[]	[]	Element names for which the cursor resizes and aligns to their bounding rectangle.
hideNativeCursor	boolean	false	Hides the OS cursor inside trigger areas when true.
breakpoint	number	1024	Minimum viewport width (px) below which the cursor is disabled.
class	string	''	Additional CSS classes to apply to the cursor element.
children	Snippet	undefined	Custom content rendered inside the cursor.
activeDataValue	ActiveDataValue bindable	{ activeDataName: '', activeDataElement: null }	Bindable. Tracks the active data-interactive-cursor name and its DOM element.
isActive	boolean bindable	false	Bindable. true while the cursor is inside a trigger area.

---

Data Attributes

Attribute	Description
data-interactive-cursor-area	Marks a container as a cursor tracking zone. Mouse enter/leave is tracked here.
data-interactive-cursor="value"	Marks a child element with a name used to match scaleOnActive and useDataElementRect.

<div data-interactive-cursor-area>
	<div data-interactive-cursor="image">Image Element</div>
	<div data-interactive-cursor="card">Card Element</div>
</div>

---

Styling

Default Classes

• .lw-interactive-cursor — base cursor styles (fixed position, hidden by default).
• .lw-interactive-cursor.active — applied while the cursor is inside a trigger area.

CSS Variables

Variable	Default	Description
--size	32px	Driven by defaultSize.

Example

.lw-interactive-cursor {
	background-color: white;
	border-radius: 50%;
}
.lw-interactive-cursor.active {
	background-color: blue;
}

---

Advanced: interactiveCursor function

For headless / programmatic use, the core function is exported directly:

import { interactiveCursorFN } from '@lostisworld/svelte-interactive-cursor';

const cursor = interactiveCursorFN(cursorElement, {
	defaultSize: 32,
	scaleOnActive: [{ element: 'btn', scaleMultiplicator: 2 }],
	duration: 500,
	easing: 'linear',
	useDataElementRect: ['card'],
	hideNativeCursor: false
});

cursor.init();

// destroy:
cursor.destroy();

Returned object

Member	Type	Description
isActive	boolean (readonly)	Whether the cursor is inside a trigger area.
activeDataValue	ActiveDataValue (readonly)	Current active element name and reference.
init()	() => void	Attach event listeners and start tracking.
destroy()	() => void	Remove event listeners and cancel animations.

---

Performance

• RAF throttling — mousemove is throttled to one animation call per frame via requestAnimationFrame, preventing excessive work at 200+ events/sec.
• Cached layout reads — offsetWidth/offsetHeight are read once at init; getBoundingClientRect() is only called when the hovered element changes.
• O(1) scale lookup — scaleOnActive is converted to a Map at init for constant-time lookups per frame.
• Single module import — the core module is loaded once across all component instances on the page via a shared Promise cache.
• will-change: transform — applied only on .active to promote the element to a compositor layer while animating.
• Resize/scroll rect invalidation — the cached bounding rect is recalculated on resize and scroll so useDataElementRect positions remain accurate.

---

Notes

• Reduced Motion: Automatically disabled on mount if the user prefers reduced motion. Also responds to OS-level changes mid-session without a page reload.
• Responsive: Disabled below the configured breakpoint (default 1024px).
• Always place data-interactive-cursor-area on the parent container of your interactive elements.

---

Contributing

Contributions are welcome!

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes with clear and descriptive messages.
4. Submit a pull request.

---

License

This project is licensed under the MIT License.