JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 127
  • Score
    100M100P100Q75089F
  • License MIT

A tiny, customizable, easy-to-use, framework-Agnostic, and high performance cursor following effect.

Package Exports

  • cursorwith-ts

Readme

cursorwith-ts

cursorwith logo

Tiny (~7 kB) · Zero dependency · TypeScript-first · Framework agnostic · High performance

npm version downloads license

A tiny, zero-dependency, TypeScript-powered cursor trail / follow effect for modern web apps.

🔥 Features

  • Tiny: ~7 kB (gzipped) output
  • Zero runtime dependencies
  • Complete TypeScript declarations
  • Works with any framework (Vue / React / Svelte / Vanilla ...)
  • Smooth animation via Canvas (no layout thrash / minimal main thread impact)
  • Configurable follow strategies (e.g. time-based)

🎈 Tiny

Just ≈ 7 kB. Import, instantiate, done.

import { CreateCursorWith } from 'cursorwith-ts/core'; // ~7 kB gzipped

🚀 Zero-Dependency

No third-party libraries are required; all functionality is implemented internally, minimizing project complexity.

🔒 TypeScript Support

Written entirely in TypeScript across the stack, complete with type definitions to enhance development safety.

import type { CursorWithOptions } from 'cursorwith-ts/types';

🍭 Framework-Agnostic

Pure implementation – drop it into Vue, React, Angular, Svelte, Solid or plain HTML.

Vue Example (App.vue)

import { CreateCursorWith } from 'cursorwith-ts/core';
import { follow } from 'cursorwith-ts/use';
import { onMounted, onBeforeUnmount, ref } from 'vue';

const cursorWith = ref<InstanceType<typeof CreateCursorWith> | null>(null);
onMounted(() => {
  cursorWith.value = new CreateCursorWith({
    style: { 
      radius: 10, 
      color: 'rgba(0,0,0,0.1)', 
      borderWidth: 1, 
      borderColor: 'rgba(0,0,0,1)' 
    }
  });
  cursorWith.value.use(follow({ type: 'time', timeRatio: 0.04 }));
});
onBeforeUnmount(() => {
  cursorWith.value?.destroy();
});

React Example (App.tsx)

import { useEffect, useRef } from 'react';
import { CreateCursorWith } from 'cursorwith-ts/core';
import { follow } from 'cursorwith-ts/use';

export default function App() {
  const cursorRef = useRef<InstanceType<typeof CreateCursorWith> | null>(null);

  useEffect(() => {
    cursorRef.current = new CreateCursorWith({
      style: { 
        radius: 10, 
        color: 'rgba(0,0,0,0.1)', 
        borderWidth: 1, 
        borderColor: 'rgba(0,0,0,1)' 
      }
    });
    cursorRef.current.use(follow({ type: 'time', timeRatio: 0.04 }));

    return () => {
      cursorRef.current?.destroy();
    };
  }, []);

  return <></>;
}

⚡️ High Performance

Canvas-based rendering only. No layout / reflow thrashing; minimal overhead per frame.

📦 Install

# npm
npm install cursorwith-ts

# pnpm
pnpm add cursorwith-ts

# yarn
yarn add cursorwith-ts

Usage

[!TIP] cursorwith-ts only supports ESM (native modules) and CDN usage.

ES6 Modules

import { CreateCursorWith } from 'cursorwith-ts/core';
import { follow } from 'cursorwith-ts/use';

const cw = new CreateCursorWith({
  style: { 
    radius: 10, 
    color: 'rgba(0,0,0,0.1)', 
    borderWidth: 1, 
    borderColor: '#000000' 
  }
});
cw.use(follow({ 
  type: 'time', 
  timeRatio: 0.04 
}));

CDN (unpkg)

<script type="module">
  import { CreateCursorWith, follow } from 'https://unpkg.com/cursorwith-ts@latest/dist/index.js';
  const cw = new CreateCursorWith({
    style: { radius: 10, color: 'rgba(0,0,0,0.1)', borderWidth: 1, borderColor: '#000000' }
  });
  cw.use(follow({ type: 'time', timeRatio: 0.04 }));
</script>

TypeScript Support

cursorwith-ts ships full declaration files – no extra config needed.

import { CreateCursorWith } from 'cursorwith-ts/core';
import type { CursorWithOptions } from 'cursorwith-ts/types';
import { follow } from 'cursorwith-ts/use';

const options: CursorWithOptions = {
  style: { 
    radius: 10, 
    color: 'rgba(0,0,0,0.1)', 
    borderWidth: 1, 
    borderColor: '#000000' 
  }
};
const cw = new CreateCursorWith(options);
cw.use(follow({ type: 'time', timeRatio: 0.04 }));

🌍 Environment Requirements

  • Modern browsers supporting ES modules & Canvas

⚙️ Minimal API (Quick Reference)

import { CreateCursorWith } from 'cursorwith-ts/core';
import { follow } from 'cursorwith-ts/use';

const instance = new CreateCursorWith({
  style: { radius: 10, color: 'rgba(0,0,0,0.1)' }
});
instance.use(follow({ type: 'time', timeRatio: 0.04 }));

// Later
instance.destroy();
Option Path Type / Values Description
style.radius number Circle radius in px
style.color string (CSS color) Fill color
style.borderWidth number Border stroke width
style.borderColor string Border stroke color
follow.type `'time' 'gap'` (example)
follow.timeRatio number Time easing factor (for time mode)
... ... ...

For full option details see the documentation

🤝 Contributing

PRs welcome. Please run lint & build before submitting:

pnpm lint && pnpm build

📄 License

MIT © 2025-present

📝 Changelog

See CHANGELOG