cursorwith-ts

🔥 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 
}));

// Hover effect (recommended to set containers)
// const container = document.body;
// const cw = new CreateCursorWith({ style: { radius: 12, color: '#00000022' }, container });
// cw.use(hoverEffect({ scope: { class: ['demo'] }, padding: 10, container }));

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 strategy mode | | 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