{"id":23698551,"url":"https://github.com/lostis-world/svelte-interactive-cursor","last_synced_at":"2025-10-19T13:51:40.238Z","repository":{"id":270266428,"uuid":"909384164","full_name":"LoStis-World/svelte-interactive-cursor","owner":"LoStis-World","description":"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.","archived":false,"fork":false,"pushed_at":"2025-01-13T17:19:47.000Z","size":1992,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-29T09:48:08.775Z","etag":null,"topics":["custom-cursor","svelte","svelte5","sveltekit"],"latest_commit_sha":null,"homepage":"https://lostis-world.github.io/svelte-interactive-cursor/","language":"Svelte","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LoStis-World.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-28T14:43:50.000Z","updated_at":"2025-02-08T17:04:35.000Z","dependencies_parsed_at":"2024-12-29T21:25:25.075Z","dependency_job_id":"eb1a973c-8776-4b2c-9295-66604ae18733","html_url":"https://github.com/LoStis-World/svelte-interactive-cursor","commit_stats":null,"previous_names":["lostis-world/svelte-interactive-cursor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/LoStis-World/svelte-interactive-cursor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoStis-World%2Fsvelte-interactive-cursor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoStis-World%2Fsvelte-interactive-cursor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoStis-World%2Fsvelte-interactive-cursor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoStis-World%2Fsvelte-interactive-cursor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LoStis-World","download_url":"https://codeload.github.com/LoStis-World/svelte-interactive-cursor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoStis-World%2Fsvelte-interactive-cursor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279824116,"owners_count":26232320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-19T02:00:07.647Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-cursor","svelte","svelte5","sveltekit"],"created_at":"2024-12-30T07:17:35.183Z","updated_at":"2025-10-19T13:51:40.207Z","avatar_url":"https://github.com/LoStis-World.png","language":"Svelte","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InteractiveCursor Component\n\nThe `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.\n\n### [Live Demo](https://lostis-world.github.io/svelte-interactive-cursor/)\n\n[CHANGELOG](./CHANGELOG.md)\n\n![](./static/images/interactive-cursor-preview.gif)\n\n---\n\n## Installation\n\nYou can install the `InteractiveCursor` component using npm or pnpm:\n\n### Using npm\n\n```bash\nnpm install @lostisworld/svelte-interactive-cursor\n```\n\n### Using pnpm\n\n```bash\npnpm add @lostisworld/svelte-interactive-cursor\n```\n\n---\n\n## Features\n\n1. **Dynamic Resizing**: The cursor adjusts its size and position dynamically when hovering over elements specified in the `useDataElementRect` property.\n2. **Scaling on Interaction**: Scale transformations can be applied to the cursor when hovering over specified elements using `scaleOnActive`.\n3. **Animation Control**: Smooth animations with customizable duration using CSS transitions and `KeyframeAnimationOptions`.\n4. **Custom Icons**: Allows custom rendering inside the cursor element using the `children` property.\n5. **State Exposure**: Exposes `activeDataValue` to track the active interactive element and its name dynamically.\n6. **Responsive Design**: Automatically disables the interactive cursor for small screens or when reduced motion is preferred.\n\n---\n\n### Types\n\n#### `ScaleOnActiveElement`\n\n```ts\ntype ScaleOnActiveElement = {\n\telement: string; // The name of the element (value of `data-interactive-cursor`).\n\tscaleMultiplicator?: number; // Scale factor to apply when the element is active.\n};\n```\n\n#### `InteractiveCursorOptions`\n\n```ts\ninterface InteractiveCursorOptions {\n\tdefaultSize?: number; // Default cursor size in pixels.\n\tscaleOnActive?: ScaleOnActiveElement[]; // Elements with scale factors.\n\tduration?: number; // Animation duration in milliseconds.\n\tuseDataElementRect?: string[]; // Elements that trigger cursor resizing.\n}\n```\n\n---\n\n## Usage\n\n### Basic Setup\n\nImport the `InteractiveCursor` component and include it in your Svelte application:\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n\timport InteractiveCursor from '@lostisworld/svelte-interactive-cursor';\n\u003c/script\u003e\n\n\u003cdiv data-interactive-cursor-area\u003e\n\t\u003cbutton data-interactive-cursor=\"btn\"\u003eHover me!\u003c/button\u003e\n\u003c/div\u003e\n\n\u003cInteractiveCursor\n\tdefaultSize={40}\n\tduration={300}\n\tscaleOnActive={[{ element: 'btn', scaleMultiplicator: 2 }]}\n\tuseDataElementRect={['btn']}\n/\u003e\n```\n\n### Advanced Example\n\nHere is an example with custom cursor behavior and styles:\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n\timport InteractiveCursor, {\n\t\ttype ScaleOnActiveElement\n\t} from '@lostisworld/svelte-interactive-cursor';\n\n\tlet currentCursorState = $state({ activeDataName: '', activeDataElement: null });\n\n\t// Custom cursor props\n\tconst scaleOnActive: ScaleOnActiveElement[] = [\n\t\t{ element: 'image' },\n\t\t{ element: 'video', scaleMultiplicator: 4 },\n\t\t{ element: 'link' },\n\t\t{ element: 'mixblend', scaleMultiplicator: 8 },\n\t\t{ element: 'prevslide', scaleMultiplicator: 5 },\n\t\t{ element: 'nextslide', scaleMultiplicator: 5 }\n\t];\n\n\tconst customCursorProps = [\n\t\t{ data: 'image', icon: '\u003csvg\u003e...\u003c/svg\u003e' },\n\t\t{ data: 'video', icon: '\u003csvg\u003e...\u003c/svg\u003e', cursorClass: 'bg-red-500 text-white' },\n\t\t{ data: 'link', icon: '\u003csvg\u003e...\u003c/svg\u003e', cursorClass: 'bg-sky-500 text-white' },\n\t\t{ data: 'tablist', cursorClass: 'rounded-none outline outline-2 outline-purple-500' }\n\t];\n\u003c/script\u003e\n\n\u003cdiv\u003e\n\t\u003c!-- Interactive Cursor Target Areas --\u003e\n\t\u003csection data-interactive-cursor-area\u003e\n\t\t\u003cdiv data-interactive-cursor=\"image\"\u003eImage\u003c/div\u003e\n\t\t\u003cdiv data-interactive-cursor=\"video\"\u003eVideo\u003c/div\u003e\n\t\t\u003cdiv data-interactive-cursor=\"link\"\u003eLink\u003c/div\u003e\n\t\t\u003cul data-interactive-cursor=\"tablist\"\u003e\n\t\t\t\u003cli\u003eTab 1\u003c/li\u003e\n\t\t\t\u003cli\u003eTab 2\u003c/li\u003e\n\t\t\u003c/ul\u003e\n\t\u003c/section\u003e\n\n\t\u003c!-- Interactive Cursor Component --\u003e\n\t\u003cInteractiveCursor\n\t\tbind:activeDataValue={currentCursorState}\n\t\t{scaleOnActive}\n\t\tuseDataElementRect={['tablist']}\n\t\tclass=\"rounded-full flex items-center justify-center {currentCursorState.activeDataName === ''\n\t\t\t? 'bg-white text-black'\n\t\t\t: customCursorProps.find((state) =\u003e state.data === currentCursorState.activeDataName)\n\t\t\t\t\t?.cursorClass || 'bg-white text-black'}\"\n\t\u003e\n\t\t{#each customCursorProps as { icon, data }}\n\t\t\t{#if data === currentCursorState.activeDataName \u0026\u0026 icon}\n\t\t\t\t{@html icon}\n\t\t\t{/if}\n\t\t{/each}\n\t\u003c/InteractiveCursor\u003e\n\u003c/div\u003e\n```\n\n---\n\n## Component Props\n\n| **Property**         | **Type**                                                     | **Default**                                       | **Description**                                                                                                                                |\n| -------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `defaultSize`        | `number`                                                     | `32`                                              | The default size (in pixels) of the cursor.                                                                                                    |\n| `scaleOnActive`      | `ScaleOnActiveElement[]`                                     | `[]`                                              | Array of objects specifying elements and their respective scaling factors.                                                                     |\n| `duration`           | `number`                                                     | `500`                                             | Duration of the cursor's animation in milliseconds.                                                                                            |\n| `useDataElementRect` | `string[]`                                                   | `[]`                                              | Array of element names (matched by `data-interactive-cursor`) for which the cursor dynamically resizes and aligns to their bounding rectangle. |\n| `class`              | `string`                                                     | `''`                                              | Additional classes to apply to the cursor element.                                                                                             |\n| `children`           | `Snippet`                                                    | `undefined`                                       | Custom content to render inside the cursor.                                                                                                    |\n| `activeDataValue`    | `{ activeDataName: string; activeDataElement: HTMLElement }` | `{ activeDataName: '', activeDataElement: null }` | Tracks the currently active interactive element's name and DOM reference.                                                                      |\n\n---\n\n## Data Attributes\n\n### Cursor Areas\n\n- Add `data-interactive-cursor-area` to define areas where the cursor can interact.\n- Add `data-interactive-cursor=\"value\"` to target specific elements and associate them with custom cursor behaviors.\n\nExample:\n\n```html\n\u003cdiv data-interactive-cursor-area\u003e\n\t\u003cdiv data-interactive-cursor=\"image\"\u003eImage Element\u003c/div\u003e\n\t\u003cdiv data-interactive-cursor=\"video\"\u003eVideo Element\u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Scaling on Specific Elements\n\nTo make the cursor scale when hovering over specific elements, define those elements using the `data-interactive-cursor` attribute.\n\n```svelte\n\u003cmain data-interactive-cursor-area\u003e\n\t\u003cbutton data-interactive-cursor=\"button\"\u003eHover Me\u003c/button\u003e\n\t\u003cInteractiveCursor\n\t\tdefaultSize={50}\n\t\tscaleOnActive={[{ element: 'button', scaleMultiplicator: 2 }]}\n\t/\u003e\n\u003c/main\u003e\n```\n\n---\n\n### Adapting to Element Size\n\nEnable the cursor to adapt its size and position to match specific elements.\n\n```svelte\n\u003cmain data-interactive-cursor-area\u003e\n\t\u003cdiv class=\"card\" data-interactive-cursor=\"card\"\u003eHover me!\u003c/div\u003e\n\t\u003cInteractiveCursor useDataElementRect={['card']} /\u003e\n\u003c/main\u003e\n```\n\n---\n\n## Styling\n\nThe `InteractiveCursor` component includes default styles that can be customized using the `class` prop or overriding CSS variables.\n\n### Default Classes\n\n- `.lw-interactive-cursor`: Base cursor styles.\n- `.lw-interactive-cursor.active`: Active state styles.\n\n### Example Custom Styles\n\n```css\n.lw-interactive-cursor {\n\tbackground-color: white;\n\tcolor: black;\n}\n.lw-interactive-cursor.active {\n\tbackground-color: blue;\n\tcolor: white;\n}\n```\n\n---\n\n### Helper Function: `interactiveCursor`\n\nFor advanced customization, you can use the `interactiveCursor` function to programmatically control the cursor.\n\n#### Parameters\n\n| Parameter | Type                       | Description                                             |\n| --------- | -------------------------- | ------------------------------------------------------- |\n| `cursor`  | `HTMLElement`              | Reference to the cursor DOM element.                    |\n| `options` | `InteractiveCursorOptions` | Configuration options for the cursor (see table below). |\n\n#### Configuration Options\n\n| Option               | Type                     | Default | Description                                            |\n| -------------------- | ------------------------ | ------- | ------------------------------------------------------ |\n| `defaultSize`        | `number`                 | `32`    | Default cursor size in pixels.                         |\n| `scaleOnActive`      | `ScaleOnActiveElement[]` | `[]`    | Elements that trigger scaling when hovered over.       |\n| `duration`           | `number`                 | `500`   | Animation duration in milliseconds.                    |\n| `useDataElementRect` | `string[]`               | `[]`    | Elements for which bounding rect sizes should be used. |\n\n---\n\n## Events and Methods\n\n### Properties\n\n- `isActive`: Boolean indicating whether the cursor is currently active.\n- `activeDataValue`: Tracks the current `data-interactive-cursor` name and element.\n\n### Methods\n\n- `init()`: Initializes event listeners and cursor tracking.\n- `destroy()`: Cleans up event listeners and animations.\n\n---\n\n## Notes\n\n- **Reduced Motion**: Automatically disables animations for users with reduced motion preferences.\n- **Responsive Design**: Disables the interactive cursor on smaller screens (e.g., mobile devices).\n- Always ensure the `data-interactive-cursor-area` attribute is present on interactive parent elements.\n\nThis 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!\n\n---\n\n## Contributing\n\nContributions are welcome! Please ensure all changes are well-documented and tested.\n\n1. Fork the repository.\n2. Create a new branch for your feature or bugfix.\n3. Commit your changes with clear and descriptive messages.\n4. Submit a pull request.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/LoStis-World/svelte-interactive-cursor/blob/main/LICENCE).\n\nHere’s the updated documentation for your `InteractiveCursor` component based on the provided code:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostis-world%2Fsvelte-interactive-cursor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flostis-world%2Fsvelte-interactive-cursor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostis-world%2Fsvelte-interactive-cursor/lists"}