About The Project

Flow Cursor brings the smooth, magnetic iPad-style cursor effect to any Svelte 5 app. It is a native Svelte 5 port of CatsJuice/ipad-cursor, keeping the original algorithm and defaults intact while exposing a first-class Svelte action as the main entry point.

Why use it:

• Idiomatic Svelte 5 — bind the cursor to any element with use:flowCursor.
• Zero markup requirements — no data-cursor attributes needed.
• Lazy & self-cleaning — the action auto-initialises the controller on first use and tears everything down when the host element is removed.
• Imperative escape hatch — the original initCursor / updateCursor / updateConfig API is re-exported for advanced integrations.

Built With

Getting Started

Add Flow Cursor to a Svelte 5 project in a few seconds.

Prerequisites

• Node.js >= 18

• Svelte ^5.0.0 (peer dependency)

  npm create svelte@latest my-app

Installation

1. Install the package

   npm install flow-cursor

2. Use the action in any component

   <script>
     import { flowCursor } from 'flow-cursor';
   </script>
   
   <div use:flowCursor={{ type: 'block' }}>Block cursor</div>
   <span use:flowCursor={{ type: 'text' }}>Text cursor</span>

Usage

Action API (recommended)

The action is the idiomatic Svelte entry point. It runs in the browser only and lazily initialises the controller the first time it sees a host element.

<script>
  import { flowCursor } from 'flow-cursor';
</script>

<!-- Block cursor that hugs the host element -->
<div use:flowCursor={{ type: 'block' }}>…</div>

<!-- Text cursor: a thin vertical bar matching the host's font-size -->
<p use:flowCursor={{ type: 'text' }}>…</p>

<!-- Per-element style override (merged on top of `blockStyle`) -->
<div
  use:flowCursor={{
    type: 'block',
    style: { background: 'rgba(124, 92, 255, 0.4)', radius: '50%' }
  }}
>
  …
</div>

You can also pass a data-cursor-style compatible string:

<div
  use:flowCursor={{ type: 'block', style: 'background: red; radius: 8px' }}
>
  …
</div>

Initial config

If you need to customise the cursor before any action runs, pass initConfig to the action — it is forwarded to the lazy init() call:

<div
  use:flowCursor={{
    type: 'block',
    initConfig: { enableLighting: true, adsorptionStrength: 18 }
  }}
>
  …
</div>

…or call initCursor(config) explicitly from <script> / onMount.

Imperative API

Mirrors the original ipad-cursor 1:1. Useful when the action does not fit (e.g. canvas-heavy apps or fine-grained lifecycle control).

<script>
  import { onDestroy, onMount } from 'svelte';
  import { initCursor, disposeCursor, updateConfig } from 'flow-cursor';

  onMount(() => initCursor({ enableLighting: true }));
  onDestroy(() => disposeCursor());

  // Reactive: re-applied when `theme` changes
  $effect(() => {
    updateConfig({ normalStyle: { background: 'rgba(0,0,0,0.5)' } });
  });
</script>

The data-cursor="text" / data-cursor="block" attributes still work — call updateCursor() after you mutate the DOM, or pass enableAutoUpdateCursor: true in the config.

cursor controller

The shared singleton — useful for advanced integrations or for reading cursor.ready from a component.

<script>
  import { cursor } from 'flow-cursor';
</script>

{#if cursor.ready}
  <p>Cursor is live.</p>
{/if}

For the canonical types, see src/lib/types.ts.

API

flowCursor action

import type { Action } from 'svelte/action';

const flowCursor: Action<HTMLElement, {
  type: 'text' | 'block' | 'normal';
  style?: IpadCursorStyle | Record<string, any> | string;
  initConfig?: IpadCursorConfig;
}>;

| Prop | Type | Notes | | ------------ | ------------------------------------------------- | ---------------------------------------------------------------- | | type | 'text' \| 'block' \| 'normal' | 'normal' removes the binding. | | style | IpadCursorStyle | Record<string, any> | string | Merged on top of the matching style. Accepts the legacy string. | | initConfig | IpadCursorConfig | Applied on the first init() call only. |

Functions

| Function | Description | | ------------------------------------- | ---------------------------------------------------- | | initCursor(config?) | Mount the fake cursor. Idempotent. | | disposeCursor() | Tear it down. | | updateCursor() | Re-scan data-cursor elements (imperative API). | | updateConfig(config) | Deep-merge a config patch. | | customCursorStyle(style) | Build a data-cursor-style string. | | resetCursor() | Clear any active hover. | | CursorType.TEXT / CursorType.BLOCK| String constants for the imperative API. |

Configuration

IpadCursorConfig mirrors the original library 1:1 — see src/lib/types.ts for the canonical reference.

| Key | Type | Default | | ------------------------ | ------------------- | ---------------- | | adsorptionStrength | number (0–30) | 10 | | className | string | 'ipad-cursor' | | blockPadding | number \| 'auto' | 'auto' | | enableAutoTextCursor | boolean | false | | enableAutoUpdateCursor | boolean | false | | enableLighting | boolean | false | | enableMouseDownEffect | boolean | false | | normalStyle | IpadCursorStyle | (see defaults) | | textStyle | IpadCursorStyle | (see defaults) | | blockStyle | IpadCursorStyle | (see defaults) | | mouseDownStyle | IpadCursorStyle | (see defaults) |

Each IpadCursorStyle accepts: width, height, radius, durationBase, durationPosition, durationBackdropFilter, background, border, zIndex, scale, backdropBlur, backdropSaturate. Set radius: 'auto' on blockStyle to inherit the host element's border-radius.

Develop

npm install
npm run dev      # demo + library in one dev server
npm run check    # type-check
npm run build    # build the library
npm test         # run unit tests (vitest)

Roadmap

• [x] Svelte 5 action wrapper
• [x] Lazy controller initialisation
• [x] Re-export of the imperative ipad-cursor API
• [ ] SSR-safe module entry
• [ ] SvelteKit example app
• [ ] Optional reduced-motion fallback

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Project Link: https://github.com/fernandomema/flow-cursor

Acknowledgments

• CatsJuice/ipad-cursor — the original library this project is ported from.
• othneildrew/Best-README-Template — README structure.
• Img Shields — for the badge assets.