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

You can install the InteractiveCursor component using npm or pnpm:

Using npm

npm install @lostisworld/svelte-interactive-cursor

Using 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 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.

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

InteractiveCursorOptions

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

Basic Setup

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

<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

Here is an example with custom cursor behavior and styles:

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

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

    // Custom cursor props
    const scaleOnActive: ScaleOnActiveElement[] = [
        { element: 'image' },
        { element: 'video', scaleMultiplicator: 4 },
        { element: 'link' },
        { element: 'mixblend', scaleMultiplicator: 8 },
        { element: 'prevslide', scaleMultiplicator: 5 },
        { element: 'nextslide', scaleMultiplicator: 5 }
    ];

    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>

<div>
    <!-- Interactive Cursor Target Areas -->
    <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>
        <ul data-interactive-cursor="tablist">
            <li>Tab 1</li>
            <li>Tab 2</li>
        </ul>
    </section>

    <!-- Interactive Cursor Component -->
    <InteractiveCursor
        bind:activeDataValue={currentCursorState}
        {scaleOnActive}
        useDataElementRect={['tablist']}
        class="rounded-full flex items-center justify-center {currentCursorState.activeDataName === ''
            ? 'bg-white text-black'
            : customCursorProps.find((state) => state.data === currentCursorState.activeDataName)
                    ?.cursorClass || 'bg-white text-black'}"
    >
        {#each customCursorProps as { icon, data }}
            {#if data === currentCursorState.activeDataName && icon}
                {@html icon}
            {/if}
        {/each}
    </InteractiveCursor>
</div>

Component Props

Data Attributes

Cursor Areas

• 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:

<div data-interactive-cursor-area>
    <div data-interactive-cursor="image">Image Element</div>
    <div data-interactive-cursor="video">Video Element</div>
</div>

Scaling on Specific Elements

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

<main data-interactive-cursor-area>
    <button data-interactive-cursor="button">Hover Me</button>
    <InteractiveCursor
        defaultSize={50}
        scaleOnActive={[{ element: 'button', scaleMultiplicator: 2 }]}
    />
</main>

Adapting to Element Size

Enable the cursor to adapt its size and position to match specific elements.

<main data-interactive-cursor-area>
    <div class="card" data-interactive-cursor="card">Hover me!</div>
    <InteractiveCursor useDataElementRect={['card']} />
</main>

Styling

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

Default Classes

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

Example Custom Styles

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

Helper Function: interactiveCursor

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

Parameters

Configuration Options

Events and Methods

Properties

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

Methods

• 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:

Changelog

Version 0.3.0 (Latest Release)

Added

• State Management Enhancements:
  • Introduced activeDataValue to expose the currently active interactive element's name and DOM reference.
• Custom Rendering Support:
  • Added children property to allow custom rendering inside the cursor element.
• Enhanced Responsiveness:
  • Automatically disables the interactive cursor for small screens (width < 1024px) or when prefers-reduced-motion is enabled.
• Dynamic Scaling:
  • Cursor dynamically adjusts size and position when interacting with elements specified in useDataElementRect.
• Custom Animation Control:
  • Support for KeyframeAnimationOptions to define animation properties like duration and fill mode.

Changed

• Reactivity Refactor:
  • Improved reactive state handling using $state and $effect for smoother updates.
• Cursor Initialization:
  • Moved initialization logic to onMount to ensure the component properly handles dynamic DOM updates.

Fixed

• Event Listeners:
  • Ensured proper cleanup of event listeners to avoid memory leaks.
• Bounding Rect Handling:
  • Fixed issues with incorrect calculations for element bounding rectangles when using useDataElementRect.

Version 0.2.0 (Latest Release)

New Features

• Support for dataElementRect Tracking:
  • Cursor now adjusts its size and position dynamically to match target element dimensions when specified in the useDataElementRect prop.
  • New logic in interactiveCursor handles target bounding rectangle retrieval and animation.
• Custom Icons and Styles:
  • Added support for rendering custom icons and styles based on data-interactive-cursor values, allowing highly customized interaction feedback.
  • Example properties include cursorClass for styles and icon for rendering inline SVG icons.
• Improved API:
  • Reworked activeDataValue to include both activeDataName and activeDataElement, providing more detailed feedback for active states.
• Smoother Animations:
  • Enhanced animation behavior with cleaner transitions between states.
  • Leveraged KeyframeAnimationOptions for fine-grained control.
• Prop Enhancements:
  • New useDataElementRect array prop specifies elements by their data-interactive-cursor name to trigger custom size adjustments.
  • Updated activeDataValue binding to enable live tracking of active interaction states.

Code Improvements

• Refactored State Management:
  • Centralized state logic using $state and $effect for reactive bindings.
  • Simplified cursor animation logic for better maintainability.
• Improved Cleanup:
  • Ensured proper cleanup of event listeners and animations during component destruction.
• Accessibility Enhancements:
  • The cursor component is now aria-hidden by default, ensuring it does not interfere with screen readers.

Version 0.1.1 (Previous Release)

Features

• Basic Interactive Cursor:
  • Initial implementation of a custom cursor component with hover tracking.
  • Basic animation on hover over data-interactive-cursor-area elements.
• Configurable Props:
  • Included props for defaultSize, activeSizeMultiplicator, and duration to customize cursor appearance and behavior.
• Area Tracking:
  • Allowed the cursor to activate when hovering over designated data-interactive-cursor-area elements.

Limitations

• No support for resizing or repositioning the cursor based on target element dimensions.
• Lacked advanced customization for icons or styles associated with specific data-interactive-cursor values.
• Minimal state feedback for interaction.