Flow Cursor

The cursor that flows on the web — a Svelte 5 port of the iPad-cursor effect.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Action API (recommended)
   • Imperative API
   • `cursor` controller
4. API
5. Configuration
6. Roadmap
7. Contributing
8. License
9. Contact
10. Acknowledgments

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.

(back to top)

Built With

• 
• 
• 

(back to top)

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>

(back to top)

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.

(back to top)

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.

(back to top)

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)

(back to top)

Roadmap

• Svelte 5 action wrapper
• Lazy controller initialisation
• 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).

(back to top)

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

(back to top)

License

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

(back to top)

Contact

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

(back to top)

Acknowledgments

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

(back to top)