neko-ts

A simple fun addition to your website, a neko that follows your mouse around! (or just sits there if you don't move your mouse)

Check out the demo here

Installation

npm install neko-ts

yarn add neko-ts

Usage

Simple usage

import { Neko } from "neko-ts";

document.addEventListener("DOMContentLoaded", () => {
  new Neko();
});

With all options

import { Neko, NekoSizeVariations } from "neko-ts";
import { tabby } from "neko-ts/breeds";

document.addEventListener("DOMContentLoaded", () => {
  const neko = new Neko({
    nekoId: 1,
    nekoSize: NekoSizeVariations.MEDIUM,
    speed: 10,
    animationSpeed: 100,
    defaultState: "awake",
    origin: { x: 500, y: 500 },
    parent: document.getElementById("app")!,
    breed: tabby,
  });
});

Using a preset breed

import { Neko } from "neko-ts";
import { marmalade } from "neko-ts/breeds";

const neko = new Neko({ breed: marmalade });

Custom breed (own sprite sheet)

import { Neko, breedSpriteSets } from "neko-ts";
import type { BreedConfig } from "neko-ts";

const myBreed: BreedConfig = {
  src: "/my-cat.png",
  spriteSets: breedSpriteSets,
  gap: 1,
  cols: 8,
  rows: 4,
};

const neko = new Neko({ breed: myBreed });

Hot-swapping breed at runtime

neko.setBreed(marmalade);   // swap to a preset
neko.setBreed(undefined);   // reset to built-in neko.gif

React

import { Neko } from "neko-ts";
import { tabby } from "neko-ts/breeds";
import { useEffect, useRef } from "react";

function App() {
  const neko = useRef<Neko>();

  useEffect(() => {
    if (!neko.current) {
      neko.current = new Neko({
        breed: tabby,
        origin: { x: 100, y: 100 },
      });
    }
    return () => neko.current?.destroy();
  }, []);
}

Options

| Option | Type | Default | Description | |---|---|---|---| | nekoId | number | 0 | Used as data-neko attribute and id="neko-{nekoId}" | | nekoSize | NekoSizeVariations | NekoSizeVariations.SMALL | Rendered size (32/38/42px) | | speed | number | 10 | Pixels moved per animation frame. Clamped to [10, 20]. | | animationSpeed | number | 100 | Frame refresh interval in ms (min 16ms ≈ 60fps). | | origin | {x: number, y: number} | {x: 0, y: 0} | Spawn position and sleep return position. | | parent | HTMLElement | document.body | Parent element; restricts cursor event tracking to this element. | | defaultState | "awake" | "sleep" | "awake" | Initial state. | | breed | BreedConfig | built-in neko.gif | Preset or custom sprite sheet config. Import presets from neko-ts/breeds. |

NekoSizeVariations

enum NekoSizeVariations {
  SMALL = 32,
  MEDIUM = 38,
  LARGE = 42,
}

Methods and properties

| Method/Property | Description | |---|---| | sleep() | Stops cursor tracking; neko idles in place | | wake() | Resumes cursor tracking | | destroy(id?: number) | Removes neko from DOM and clears its interval. Targets instance's id if none provided. | | setSize(size: NekoSizeVariations) | Hot-swap size without recreating neko | | setBreed(breed?: BreedConfig) | Hot-swap sprite sheet. Pass undefined to reset to built-in neko.gif | | setSpeed(speed: number) | Update movement speed. Clamped to [10, 20]. | | setAnimationSpeed(ms: number) | Update frame refresh rate in ms. Resets the interval. Min 16ms. | | size: NekoSizeVariations | Current size (read) | | isAwake: boolean | Whether neko is awake (read) | | position: {x: number, y: number} | Current viewport position of the neko center (read) |

Breeds

Import any of the 35 built-in breeds from neko-ts/breeds:

import { tabby, marmalade, calico /* ... */ } from "neko-ts/breeds";

Available breeds: ace, air, black, blue, calico, colourful, dave, dog, earth, fancy, fire, ghetto, ghost, jess, lucky, lucy, marmalade, mermaid, mike, moka, neko, neon, orange, peach, pink, rainbow, robot, royal, silversky, socks, spirit, tabby, usa, valentine, water

Each breed is a BreedConfig object that can be passed directly to the breed option or to setBreed().

Sprite sheet constants

| Export | Description | |---|---| | gifSpriteSets | Sprite layout for the built-in neko.gif (8 cols × 4 rows, no gap) | | breedSpriteSets | Sprite layout for the breed PNG sheets (8 cols × 4 rows, 1px gap) |

Use these constants when defining a custom BreedConfig.

Testing

Someone please test this in multiple frameworks. I know this works in Svelte, but I don't know about others.

• [x] Svelte
• [x] React
• [ ] Vue
• [ ] Angular
• and more...

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Credits

I used these repos as a reference and made it type-safe.

• oneko.js
• jneko