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.

$3

CHANGELOG


---

Installation

You can install the InteractiveCursor component using npm or pnpm:

$3

``bash
npm install @lostisworld/svelte-interactive-cursor
`

$3

`bash
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 using CSS transitions and KeyframeAnimationOptions.
4. Custom Icons: Allows custom rendering inside the cursor element using the children property.
5. State Exposure: Exposes activeDataValue to track the active interactive element and its name dynamically.
6. Responsive Design: Automatically disables the interactive cursor for small screens or when reduced motion is preferred.

---

$3

#### ScaleOnActiveElement

`ts
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.
};
`

#### InteractiveCursorOptions

`ts
interface InteractiveCursorOptions {
defaultSize?: number; // Default cursor size in pixels.
scaleOnActive?: ScaleOnActiveElement[]; // Elements with scale factors.
duration?: number; // Animation duration in milliseconds.
useDataElementRect?: string[]; // Elements that trigger cursor resizing.
}
`

---

Usage

$3

Import the InteractiveCursor component and include it in your Svelte application:

`svelte


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

$3

Here is an example with custom cursor behavior and styles:

`svelte


| Property | Type | Default | Description |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultSize | number | 32 | The default size (in pixels) of the cursor. |
| scaleOnActive | ScaleOnActiveElement[] | [] | Array of objects specifying elements and their respective scaling factors. |
| duration | number | 500 | Duration of the cursor's animation in milliseconds. |
| useDataElementRect | string[] | [] | Array of element names (matched by data-interactive-cursor) for which the cursor dynamically resizes and aligns to their bounding rectangle. |
| class | string | '' | Additional classes to apply to the cursor element. |
| children | Snippet | undefined | Custom content to render inside the cursor. |
| activeDataValue | { activeDataName: string; activeDataElement: HTMLElement } | { activeDataName: '', activeDataElement: null } | Tracks the currently active interactive element's name and DOM reference. |

---

Data Attributes

$3

- Add data-interactive-cursor-area to define areas where the cursor can interact.
- Add data-interactive-cursor="value" to target specific elements and associate them with custom cursor behaviors.

Example:

`html


To make the cursor scale when hovering over specific elements, define those elements using the data-interactive-cursor attribute.

`svelte


`svelte


The InteractiveCursor component includes default styles that can be customized using the class prop or overriding CSS variables.

$3

- .lw-interactive-cursor: Base cursor styles.
- .lw-interactive-cursor.active: Active state styles.

$3

`css
.lw-interactive-cursor {
background-color: white;
color: black;
}
.lw-interactive-cursor.active {
background-color: blue;
color: white;
}
`

---

$3

For advanced customization, you can use the interactiveCursor function to programmatically control the cursor.

#### Parameters

| Parameter | Type | Description |
| --------- | -------------------------- | ------------------------------------------------------- |
| cursor | HTMLElement | Reference to the cursor DOM element. |
| options | InteractiveCursorOptions | Configuration options for the cursor (see table below). |

#### Configuration Options

| Option | Type | Default | Description |
| -------------------- | ------------------------ | ------- | ------------------------------------------------------ |
| defaultSize | number | 32 | Default cursor size in pixels. |
| scaleOnActive | ScaleOnActiveElement[] | [] | Elements that trigger scaling when hovered over. |
| duration | number | 500 | Animation duration in milliseconds. |
| useDataElementRect | string[] | [] | Elements for which bounding rect sizes should be used. |

---

Events and Methods

$3

- isActive: Boolean indicating whether the cursor is currently active.
- activeDataValue: Tracks the current data-interactive-cursor name and element.

$3

- init(): Initializes event listeners and cursor tracking.
- destroy(): Cleans up event listeners and animations.

---

Notes

- Reduced Motion: Automatically disables animations for users with reduced motion preferences.
- Responsive Design: Disables the interactive cursor on smaller screens (e.g., mobile devices).
- Always ensure the data-interactive-cursor-area attribute is present on interactive parent elements.

This documentation provides clear guidance on integrating and customizing the InteractiveCursor component for a variety of use cases. Let me know if you'd like further refinements!

---

Contributing

Contributions are welcome! Please ensure all changes are well-documented and tested.

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.

Here’s the updated documentation for your InteractiveCursor` component based on the provided code: