A little guide
for little paws.

Oneko is a shadcn registry component for React. The installer copies the component, hooks, animation engine, 24 bundled skins, and skin credits into your project. You own the code. Start from a React project with shadcn configured and a working import alias.

npx shadcn@latest add https://oneko.dhrv.pw/r/oneko.json

npx shadcn@latest add https://oneko.dhrv.pw/r/oneko-classic.json

Choose one installation per project. The classic item has the same engine and component path, with only the classic coat embedded. Both add about 31 KB gzipped up front; the full item loads its other sheets (about 558 KB) only when a named skin is first rendered. Named skins such as calico need the full item; custom spriteSrc works with either. To switch versions, run the other install command and review overwritten files. Studio exports use the full install command.

Mount one cat near the root of your app. It attaches its sprite and bubble to document.body; it does not take up layout space. For a browser-only React app, import Oneko and render it directly.

import Oneko from "@/components/oneko";

export default function CatLayer() {
  return <Oneko meow={false} />;
}

In Next.js App Router, put the no-SSR dynamic import inside a client component. Render this wrapper from your layout. This also ensures the default starting position is computed in the browser.

"use client";

import dynamic from "next/dynamic";

const Oneko = dynamic(() => import("@/components/oneko"), { ssr: false });

export default function CatLayer() {
  return <Oneko meow={false} />;
}

import CatLayer from "@/components/cat-layer";

// Keep your existing layout, providers, and metadata.
// Add this once inside <body>, alongside your app content:
<CatLayer />

Any site can load the hosted build: Astro, Hugo, Jekyll, WordPress, or plain HTML. One script tag brings a cat, configured with data- attributes named after the props in kebab case. Booleans accept a bare attribute or "false"; separate several thoughts with |. Sounds default to the hosted files.

<script type="module" src="https://oneko.dhrv.pw/oneko.js" data-skin="calico" data-meow></script>

<script type="module" src="https://oneko.dhrv.pw/oneko.js"></script>
<oneko-cat skin="ginger" bubble-text="mrrp?|nap time"></oneko-cat>

import { createOneko } from "https://oneko.dhrv.pw/oneko.js";

const cat = createOneko({ skin: "tuxedo", laserPointer: true });
cat.update({ paused: true });
cat.destroy();

• The script is about 33 KB gzipped. Named skins load the first time one is used.
• When the page has a <oneko-cat> element, or the script tag has data-manual, the script does not add its own cat.
• Removing a <oneko-cat> element removes its cat. Removing an attribute returns that option to its default.
• A <oneko-cat> element fires a statechange event whose detail.state is the cat's activity.

Download one small component into your project. It takes the same props as the React component, follows prop changes, and removes the cat on unmount. The engine loads from the hosted build in the browser, so SvelteKit, Nuxt, and SolidStart can render it during SSR.

curl -o src/lib/Oneko.svelte https://oneko.dhrv.pw/frameworks/Oneko.svelte

<script>
  import Oneko from "$lib/Oneko.svelte";

  let { children } = $props();
</script>

<Oneko skin="calico" meow />
{@render children()}

curl -o src/components/Oneko.vue https://oneko.dhrv.pw/frameworks/Oneko.vue

<script setup>
import Oneko from "./components/Oneko.vue";
</script>

<template>
  <Oneko skin="calico" :speed="12" meow @state-change="console.log" />
  <RouterView />
</template>

curl -o src/components/Oneko.tsx https://oneko.dhrv.pw/frameworks/Oneko.solid.tsx

import Oneko from "./components/Oneko";

export default function App() {
  return <Oneko skin="calico" meow onStateChange={console.log} />;
}

• In Nuxt, save the file as components/Oneko.vue and it is auto-imported.
• Svelte and Solid take onStateChange as a prop; Vue emits state-change.
• Setting a prop to undefined returns that option to its default.
• To self-host, serve public/oneko.js and its oneko/ folder yourself and change ONEKO_URL at the top of the component.

Angular, Lit, Astro, and other frameworks can use the <oneko-cat> element from the hosted script. In Angular, add CUSTOM_ELEMENTS_SCHEMA to the component's schemas, bind options with [attr.skin], and listen with (statechange).

<oneko-cat [attr.skin]="skin" meow (statechange)="activity = $event.detail.state"></oneko-cat>

All props are optional. These are component defaults; the playground starts with sound off and its own cat thought. The cat and laser stop when reduced motion is enabled and return when it is disabled; set reducedMotion="rest" to keep a still, sleeping cat instead. The engine runs at 10fps, so 10 active frames is about one second. Hidden tabs and paused cats do not advance those timers.

Most props update live. initialPos is mount-only; changing persistPosition, storageKey, zIndex, or the liveStateRef object restarts the animation DOM. Suggested playground ranges are guidance, not automatic clamps unless explicitly stated below.

Choose classic, black, gray, calico, tora, catppuccin, ghost, silver, spirit, valentine, maia, vaporwave, ginger, sage, siamese, strawberry-milk, blue-frost, lavender, tuxedo, peach, honey, mocha, mint, or midnight-blue. All skins ship with the full registry; the classic-only item includes classic and supports custom spriteSrc. Neither requires a separate image download. The original 12 sheets are unchanged; 12 generated coat variants are prepared at the same frame size.

<Oneko skin="calico" scale={1.5} rotationAmount={0} meow={false} />

In the studio (/studio), open Appearance → Use your own sprite to upload a custom PNG (256 × 128 pixels, up to 256 KB) or download the classic sheet as a template. Keep its frame positions: 8 columns and 4 rows of 32 × 32 frames. Uploads stay in your browser and are saved with preferences. Selecting a built-in coat or Reset cat removes the custom sprite. The React example embeds your uploaded image as a data URL; you can also host the PNG and pass its URL through spriteSrc.

<Oneko spriteSrc="/my-sprite.png" bubbleText={["Treat inspection", "On an adventure"]} meow={false} />

The installer includes docs/oneko-skins.md with artwork provenance. Code is MIT; preserve the artwork credits and review the skin-specific notes when redistributing.

<Oneko
  followCursor={false}
  sleepEnabled
  freerunChance={0}
  meow={false}
  persistPosition={false}
  initialPos={{ x: 80, y: 120 }}
/>

• paused freezes the current activity; it does not make the cat sleep. Use paused={isDialogOpen} with your existing dialog state to pause while a dialog is open.
• followCursor={false} keeps the cat resting in one spot, with grooming, bubbles, and optional naps. Keep-out zones can still relocate it to safety. Re-enabling follows the latest pointer position.
• sleepEnabled={false} wakes a sleeping cat on the next active tick. If paused, it wakes after resuming.
• The laser toy is hidden while paused or when cursor-follow is disabled. While active, it takes priority over favorite spots.
• On touch screens, a tap on non-interactive space gives the cat a destination. Taps on buttons, links, and form controls are ignored.

Mount more than one Oneko. With chase="cat", each cat follows the one mounted before it, and the first one chases the cursor. When the leader naps, cats resting beside it doze off too. Give each cat its own storageKey so their nap spots are saved separately.

<Oneko skin="ginger" storageKey="cat:ginger" />
<Oneko skin="calico" chase="cat" storageKey="cat:calico" />
<Oneko skin="tuxedo" chase="cat" storageKey="cat:tuxedo" scale={0.5} />

The same works with the hosted script: add several <oneko-cat> elements, using chase="cat" on all but the first. Every cat element carries data-oneko-cat; only the first keeps the id oneko-react.

<Oneko napWhileTyping followFocus perchOnHover />

• napWhileTyping: the cat curls up while visitors write, and wakes when the pointer moves again. With sleepEnabled={false} it sits quietly instead.
• followFocus: keyboard users get a companion too. The cat trots to whatever Tab lands on.
• perchOnHover: rest the pointer on a link or button and the cat hops on top. Mark other elements with data-oneko-perch.
• All three are off by default and can be toggled live.

<Oneko grabbable treats />

<img src="/mug.png" alt="Coffee mug" data-oneko-knockable />
<div className="shipping-box" data-oneko-box />

• grabbable: drag the cat and let go to toss it. A plain click pets it.
• treats: double-click empty space to drop a fish. The nearest cat eats it.
• data-oneko-knockable: now and then, a resting cat walks up to the element, stares at you, and paws it off the screen. It returns a few seconds later. Only marked elements are touched, and only with a temporary animation.
• data-oneko-box: if it fits, it sits. A resting cat visits the box and naps in it for about 15 seconds. The box must be at least three quarters of the cat wide.
• timeOfDay and affection add moods by the clock and greetings for returning visitors. All of these are off by default and can be toggled live.

Every cat comes with controls: goTo walks to an element, selector, or point and stays there; say shows a bubble now; sit holds still; follow goes back to the cursor; pet and dropTreat do what they say. goTo resolves true on arrival and false if the cat is sent elsewhere first.

"use client";

import { useRef } from "react";
import Oneko, { type OnekoControls } from "@/components/oneko";

export function TourCat() {
  const cat = useRef<OnekoControls>(null);
  async function tour() {
    if (await cat.current?.goTo("#pricing")) cat.current?.say("the plans live here");
    await new Promise((done) => setTimeout(done, 3000));
    if (await cat.current?.goTo("#signup")) cat.current?.say("click me. I mean, this");
    setTimeout(() => cat.current?.follow(), 3000);
  }
  return (
    <>
      <Oneko ref={cat} />
      <button type="button" onClick={tour}>Show me around</button>
    </>
  );
}

<oneko-cat id="guide"></oneko-cat>
<script type="module" src="https://oneko.dhrv.pw/oneko.js"></script>
<script type="module">
  const cat = document.querySelector("#guide");
  await customElements.whenDefined("oneko-cat");
  if (await cat.goTo("#pricing")) cat.say("the plans live here");
</script>

createOneko() returns the same controls next to update and destroy. Vue template refs and Svelte bind:this expose them too, and the Solid component takes ref={(controls) => ...}. Add data-oneko-say="text" to any element and the nearest cat comments when the pointer rests on it or keyboard focus lands on it. say() and data-oneko-say speak even when bubbleEnabled is false; data-oneko-say stays quiet when it is off.

Cats wear a pixel witch hat from October 20 to 31, a Santa hat from December 18 to 29, and a party hat from December 30 to January 2, based on the visitor's local date, with a few themed thoughts mixed in. The hat follows the head in every frame and works with any coat. Set seasonal={false} to opt out, or force a season while testing.

<Oneko seasonal="halloween" />

Give visitors a way to send the cat away. setCatsHidden(true) hides every cat on the site, in every open tab, and the choice is remembered in localStorage under oneko:hidden. useCatsHidden() reads it in React.

"use client";

import { setCatsHidden, useCatsHidden } from "@/components/oneko";

export function CatToggle() {
  const hidden = useCatsHidden();
  return (
    <button type="button" aria-pressed={hidden} onClick={() => setCatsHidden(!hidden)}>
      Hide the cat
    </button>
  );
}

<script type="module" src="https://oneko.dhrv.pw/oneko.js"></script>
<button type="button" data-oneko-toggle>Hide the cat</button>

The hosted script keeps aria-pressed on every data-oneko-toggle element in sync and also exports setCatsHidden and areCatsHidden. Add pettable to make the cat a "Pet the cat" button that keyboard and screen-reader users can reach. It holds still while focused; Enter or Space pets it.

<Oneko
  meow={false}
  bubbleText="Dreaming of treats…"
  bubblePlacement="above"
  bubbleScale={1.2}
  bubbleDisplayFrames={60}
  bubbleCooldown={100}
/>

bubbleScale multiplies the bubble’s inherited scale without changing the cat. Auto placement prefers above and flips below near the top. Bubbles are kept inside the viewport when they fit; an oversized bubble is centered horizontally. Keep-out zones constrain the cat, not its bubble.

Custom text is used for awake idle activities. Sleeping always uses sleepy thoughts. Keep your copy cat-themed. bubbleChance controls regular chatter; zoomies have their own thoughts and timing.

Bubble styling reads --background, --foreground, and --border from your theme. It uses --font-geist-pixel-square when available, otherwise monospace. Geist Pixel is optional; the component does not require this site’s fonts.

Mark real page elements as keep-out areas or favorite spots. These attributes work without a zones prop and follow visible elements as the page moves.

<section data-oneko-zone="avoid">
  {/* Your checkout or other UI that needs room. */}
</section>
<div data-oneko-zone="attract">A cozy cat bed</div>
<Oneko meow={false} />

import Oneko, { type OnekoZone } from "@/components/oneko";

const zones: OnekoZone[] = [
  { id: "checkout", type: "avoid", selector: "#checkout", padding: 12 },
  { id: "bed", type: "attract", selector: ".cat-bed" },
  {
    id: "corner", type: "avoid",
    rect: { left: 0, top: 0, right: 160, bottom: 100 },
  },
];

export function CatLayer() {
  return (
    <Oneko zones={zones} zoneAttractionChance={0.3}
      zoneAttractionDuration={4000} meow={false} />
  );
}

• OnekoZone has id, type (avoid or attract), and either selector or rect. A selector takes precedence and includes all matching visible elements. Use distinct IDs for separate definitions.
• Rectangles use viewport CSS pixels with left, top, right, and bottom. Optional padding adds extra space around avoid zones. Invalid selectors and empty rectangles are ignored.
• Avoid zones protect the entire scaled, tilting cat, even during zoomies. A new zone around the cat moves it to the nearest safe spot. If no room remains, the cat hides until space returns.
• Favorites are checked every five seconds. A visit includes travel time, followed by an eight-second break after it ends. Offscreen favorites and favorites inside keep-out areas are skipped.
• Zones are sampled at the 10fps tick. Keep-out boundaries take priority; paused cats do not reconcile moving zones until resumed.

Sound is off by default, and the registry does not include audio files. The quickest way to enable it is to set meow and point soundBasePath at the hosted copy. To self-host instead, copy public/cat-sounds/ from the source repository into your app’s public assets, preserving the .ogg filenames. Browsers may require user interaction before audio can play.

<Oneko meow soundBasePath="https://oneko.dhrv.pw/cat-sounds" />

<Oneko meow volume={0.3} soundBasePath="/assets/cat-sounds" />

soundBasePath also accepts an absolute directory URL. Mute and volume apply to future playback; sounds already playing can finish. Sleeping audio uses the purr pool.

In the studio's Behavior tab, Sleepy, Curious, and Playful presets adjust movement settings. They preserve artwork, thoughts, sound, pause, cursor-follow, nap, and visibility choices. The selected preset follows the current slider values; presets do not add a runtime prop.

In Export, Copy share link opens a built-in coat and settings in the studio. The configuration stays in the URL fragment and is limited to 8192 characters. Shared settings take precedence over saved browser preferences on load. Invalid links leave saved preferences intact.

Download configuration includes every setting, thought, and custom sprite. Import configuration accepts a versioned JSON file up to 512 KB and replaces the current settings, including sound and visibility. Invalid versions, settings, or artwork leave your cat unchanged. Custom sprites and oversized configurations use files instead of share links.

<Oneko storageKey="my-site:cat" persistPosition meow={false} />

Only position is saved, using a versioned pair of finite coordinates. Valid legacy positions are migrated; malformed values and stored animation internals are ignored. Restored positions are clamped to the viewport. Saving runs when the page hides, on pagehide, and on component cleanup. Storage failures are ignored. A saved spot takes precedence over initialPos. Use persistPosition={false} for a predictable starting position or when saving is unwanted.

The component does not save its configuration props. The hosted playground separately remembers its controls under oneko:playground:v1. Copy your cat in the instantly available install panel exports your selected configuration. Open customization and install panels keep the cat outside; zone sample spots sit below the controls.

"use client";

import { useState } from "react";
import Oneko, { type CatActivityState } from "@/components/oneko";

export function CatActivity() {
  const [activity, setActivity] = useState<CatActivityState>("idle");
  return (
    <>
      <Oneko meow={false} onStateChange={setActivity} />
      <p>Cat activity: {activity}</p>
    </>
  );
}

Activity values are idle, moving, sleeping, scratchSelf, tired, alert, scratchWallN, scratchWallS, scratchWallE, scratchWallW, and freerun. In a Next.js app, use the no-SSR wrapper pattern from installation for the Oneko import.

import { useRef } from "react";
import type { CatLiveState } from "@/components/oneko";

// Inside your client component:
const liveStateRef = useRef<CatLiveState>({
  state: "idle", posX: 0, posY: 0, velMag: 0,
  idleTime: 0, distToMouse: 0, frameCount: 0,
  freerunActive: false, freerunTimer: 0, bubbleVisible: false,
  pathLength: 0, obstacleCount: 0,
});

// Pass liveStateRef={liveStateRef} to Oneko.
// Read liveStateRef.current when needed; writes do not rerender React.

onPet, onCatchCursor, onSleep, onToss, and onTreat report moments worth celebrating. With the hosted script, listen for pet, catchcursor, sleep, toss, and treat events on the <oneko-cat> element; the details match the callbacks. Vue components emit pet, catchCursor, sleep, toss, and treat.

<Oneko onCatchCursor={() => setCatches((count) => count + 1)} onPet={({ affection }) => setAffection(affection)} affection />

CatLiveState exposes activity, position, speed, idle ticks, cursor distance, total ticks, zoomies status/time, bubble visibility, and nearby movement information. Public types OnekoProps, OnekoControls, OnekoSeason, OnekoSkin, OnekoZone, CatActivityState, and CatLiveState are exported from @/components/oneko.

Copy this prompt into your coding agent with your project open. It points to the same documentation in Markdown, gives the exact install command, and asks the agent to adapt to your existing app.

Add the Oneko pixel cat to this project using its shadcn registry component.

Read https://oneko.dhrv.pw/llms.txt, then https://oneko.dhrv.pw/docs.md for the full API and integration recipes. Fetch https://oneko.dhrv.pw/r/oneko.json if you need the exact installable source.

1. Inspect the framework, package manager, existing shadcn setup, import aliases, theme tokens, and client/server boundaries. Preserve unrelated changes.
2. Install with: npx shadcn@latest add https://oneko.dhrv.pw/r/oneko.json
3. Mount one Oneko instance in an appropriate client component. For Next.js App Router, use the documented dynamic import with ssr: false inside a client wrapper, then render that wrapper from the layout.
4. Start with meow={false} unless the sound assets are installed. Keep the built-in reduced-motion behavior, pixel art, and theme-token bubble styling. Keep cat thoughts cat-themed, and sleeping thoughts sleepy.
5. Use documented props to match this site. Put data-oneko-zone="avoid" on sensitive UI that needs space. Use initialPos with persistPosition={false} when a fixed starting spot is required. Do not add new settings unless needed.
6. Check desktop and touch behavior, light and dark themes, keyboard controls, and reduced motion. Run the project’s relevant lint, type, test, and build checks. Report the files changed, chosen props, and any missing sound assets.

Implement the integration in this project. Do not deploy or publish it.

Agents can read /llms.txt for discovery, /docs.md or /llms-full.txt for the complete guide, and /r/oneko.json for the installable source. These resources are public and need no login. The HTML guide is rendered on the server, so it is readable without JavaScript.

• No cat? Check that it is mounted in the browser. With reduced motion, the cat is hidden unless reducedMotion="rest". Keep-out zones covering the whole viewport can also hide it.
• Cat stays still? Check paused, followCursor, followDistance, and whether the tab is hidden. A resting cat may need the cursor moved farther away before it chases.
• Starting spot ignored? A saved position overrides initialPos. Disable persistence or use a new storage key, then remount the component.
• No purrs? Check meow, volume, the sound directory and filenames, and whether the page has received a user interaction. Sound files are not part of the registry download.
• Cat covers a dialog? Lower zIndex or use paused with your dialog state. The cat is mounted on document.body, so a parent’s stacking context does not contain it.
• Bubble font differs? Load Geist Pixel and expose --font-geist-pixel-square, or keep the monospace fallback. Define theme variables in both light and dark modes.