Interactive / COMPONENT

Pixel Cat

A tiny, source-first pixel-art cat companion that wanders within its parent by default, with configurable coat patterns, poses, cursor curiosity, and petting reactions.

Live preview
Parent container world (ResizeObserver bounded)
Breed:
View the Pixel Cat source on GitHub

How it works

A ResizeObserver measures the parent boundary and constrains autonomous movement to it. Optional pointer curiosity and petting interactions trigger pose and particle responses.

Accessibility

The cat supports reduced-motion preferences. Interactive petting can be disabled, and the component remains within its measured parent container by default.

Limitations

Parent-bounded movement needs a parent with measurable dimensions. In a zero-size parent, the component uses fallback bounds until it can measure the container.

Features

  • Wanders inside its parent container by default, with an optional viewport boundary.
  • Calculates movement boundaries dynamically and responds to parent resizing.
  • Uses ResizeObserver to clamp the cat inside resized parent boundaries.
  • Six coat palettes: White, Orange Tabby, Midnight with golden eyes, Calico, Silver Gray, and Theme.
  • Multiple authentic pixel-art poses: idle, walk, sit, sleep (loaf), alert, happy, stretch, groom.
  • Autonomous wandering engine with natural pacing and idle variation.
  • Cursor awareness: perks ears, tracks movement, steps curiously closer, or playfully scampers away.
  • Interactive petting reaction: joyful bounce, speech bubbles, and floating heart particles.
  • Configurable speed, size, padding, position, and fixed pose locks.
  • Full reduced-motion accessibility support.

Installation

Choose the CLI command or install the component manually.

Package manager
$ npx @istmx/ui add pixel-cat

Copies the install command for your selected package manager.

Dependencies

ReactMotionTailwind CSSclsxtailwind-merge

Usage

Import the component from the file you copied it to, then use it like any other React component.

Usage
import { PixelCat } from '@/components/ui/pixel-cat'
 
export default function InteractiveCard() {
  return (
    <div className="relative h-64 w-full overflow-hidden rounded-xl border border-border bg-card p-5">
      <h3 className="font-semibold text-foreground">Interactive Card</h3>
      <p className="text-muted-foreground text-sm">
        The cat wanders exclusively inside this container.
      </p>
 
      {/* Wandering orange tabby cat */}
      <PixelCat breed="orange" size={36} wandering={true} />
    </div>
  )
}

Composition

Composition
PixelCat
├── Container boundary tracker (ResizeObserver)
├── Parametric 32×32 pixel canvas sprite engine
├── Wandering & cursor curiosity controller
├── Speech bubble notification
└── Heart emote particles

API reference

size?number

Size in pixels (width and height). Defaults to 36.

breed?'white' | 'orange' | 'black' | 'calico' | 'gray' | 'theme'

Coat pattern / fur palette. Defaults to 'white'.

palette?Record<1 | 2 | 3 | 4, string>

Custom 4-color palette overriding the breed colors.

wandering?boolean

Whether the cat autonomously wanders within its parent container. Defaults to true.

speed?number

Movement speed multiplier. Defaults to 1.

boundary?'parent' | 'viewport'

Movement boundary: 'parent' container (default) or 'viewport'.

position?PixelCatPosition

Initial placement: 'random', 'center', a corner, or { x, y } percentages from 0 to 100.

initialPose?PixelCatPose

Initial pose when rendered. Defaults to 'sit'.

pose?PixelCatPose

Fixed pose to lock the cat into (e.g. sleep, groom, sit). Disables random pose changes.

interactive?boolean

Whether clicking or tapping pets the cat. Defaults to true.

cursorInteraction?boolean

Whether the cat turns toward and responds to cursor proximity inside the container. Defaults to true.

messages?string[]

Custom list of speech bubble texts when meowing or petted.

showBubble?boolean

Whether speech bubbles are displayed. Defaults to true.

onPet?(state: { count: number; pose: PixelCatPose }) => void

Callback fired when user pets (clicks) the cat.

onPoseChange?(pose: PixelCatPose) => void

Callback fired when pose changes.

padding?number

Inner padding in pixels from container edges. Defaults to 8.

className?string

Additional CSS classes for the container wrapper.

style?CSSProperties

Inline styles merged onto the animated wrapper after its computed size and position.

The listed props match the current component implementation.

Exports include PixelCatProps, PixelCatBreed, PixelCatPose, PixelCatPosition, CAT_PALETTES, CAT_SIZE, and CAT_FEET_Y.

Data attributes

Pixel Cat does not expose custom data attributes.

Examples

Place PixelCat inside any parent container with relative positioning and overflow-hidden. The cat automatically measures the container width and height using ResizeObserver, clamping its movement area so it never leaves the frame.

Credits & inspiration

Created by Aryan (istmX) for ISTMX. The source-first, copy-and-own philosophy is inspired by shadcn/ui. About the creator