cursorwith-ts

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

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

🔥 Features

• Tiny: ~4 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 ≈ 4 kB. Import, instantiate, done.

import { CreateCursorWith } from 'cursorwith-ts'; // ~4 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';

🍭 Framework-Agnostic

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

Vue Example (App.vue)

import { CreateCursorWith } from 'cursorwith-ts';
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)' 
        }
    follow: { 
        type: 'time', 
        timeRatio: 0.04
        }
  });
});
onBeforeUnmount(() => {
  cursorWith.value?.destroy();
});

React Example (App.tsx)

import { useEffect, useRef } from 'react';
import { CreateCursorWith } from 'cursorwith-ts';

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)' 
        },
      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';

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

CDN (unpkg)

<script type="module">
  import { CreateCursorWith } 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' },
    follow: { type: 'time', timeRatio: 0.04 }
  });
</script>

TypeScript Support

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

import { CreateCursorWith } from 'cursorwith-ts';
import type { CursorWithOptions } from 'cursorwith-ts';

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

🌍 Environment Requirements

• Modern browsers supporting ES modules & Canvas

⚙️ Minimal API (Quick Reference)

import { CreateCursorWith } from 'cursorwith-ts';

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

// Later
instance.destroy();

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