✨ Overview

@usespaceui/squishmoji is a free, lightweight React and TypeScript library that generates charming, deterministic squishy SVG avatars and emojis. Every seed creates a reproducible persona with expressive animated eyes, lifelike breathing physics, dynamic gaze tracking, and reactive interaction states.

• 100% Deterministic: Same seed and options always produce the same layout, palette, and contours.
• Pure SVG: Infinitely scalable, no canvas, no remote images.
• Alive with Motion: Breathing, optional wobble, gaze drift, and blinks.
• Interactive: Optional hover and click expression reactions.
• Core API without React: createAvatar works in Node, SSR, and vanilla JS. Use frozenAt or createAvatar for static markup.

📦 Installation

pnpm add @usespaceui/squishmoji
# or
npm install @usespaceui/squishmoji
# or
yarn add @usespaceui/squishmoji

@usespaceui/gradients is installed automatically. The /react entry needs React 18+. The core import does not.

🚀 Usage

React Component

You can import either Squishmoji or Avatar:

import { Squishmoji } from "@usespaceui/squishmoji/react";

export default function UserProfile() {
  return (
    <Squishmoji
      seed="space-explorer"
      shape="cat"
      expression="loving"
      size={120}
      className="rounded-full"
      animate
      animOnClick
      animOnHover
    />
  );
}

Set animate={false} whenever static rendering or reduced motion is preferred.

Framework-Agnostic Core API (Node.js, SSR, Vanilla JS)

Generate raw SVG markup or structured JSON data directly for server environments, API routes, or vanilla JavaScript:

import {
  createAvatar,
  resolveLayout,
  renderLayout,
  SquishOutputFormat,
} from "@usespaceui/squishmoji";

// 1. Generate raw SVG markup (default)
const svg = createAvatar("space-explorer", {
  shape: "ufo",
  expression: "amazed",
  size: 256,
  backgroundStyle: "solid",
});

// 2. Generate structured JSON data with ready-to-use Data URI
const avatarJson = createAvatar("space-explorer", {
  shape: "cat",
  expression: "loving",
  format: "json", // or SquishOutputFormat.json
});
// { seed, shape, expression, size, backgroundStyle, svg, dataUri, layout }

// 3. Two-phase layout computation and custom rendering pipeline
const layout = resolveLayout("space-explorer", {
  shape: "ghost",
  expression: "excited",
});
const renderedSvg = renderLayout(layout, {
  size: 256,
  backgroundStyle: "taygeta",
});

⚙️ React Props

| Prop | Type | Default | Description | | :---------------- | :--------------------------------- | :----------- | :-------------------------------------------------------------------------------------- | | seed | string | "Space UI" | Deterministic identity. Drives the palette; with "all" it also picks catalog options. | | shape | SquishShape | "all" | "circle" | Body silhouette, or "all" to pick deterministically from the seed. | | expression | SquishExpression | "all" | "neutral" | Eye expression, or "all" to pick deterministically from the seed. | | backgroundStyle | SquishBackgroundStyle | "all" | "solid" | Fill style, or "all" to pick deterministically from the seed. | | size | number \| string | 120 | Width and height of the SVG. | | className | string | — | Class on the host span (same pattern as @usespaceui/avatars). | | style | CSSProperties | — | Inline styles on the host span. | | animate | boolean | true | Enables autonomous breathing, natural gaze drift, and periodic blinking. | | animWobble | boolean | false | Adds gentle floating wobble physics transforms. | | animOnClick | boolean | false | Click cycles angry / excited. Off by default. | | animOnHover | boolean | false | Hover switches to surprised (loving if already surprised). Off by default. | | gazeOffsetY | number | 0 | Vertical eye offset in SVG units. | | splitOffset | number | 0 | Horizontal split for divergent or cross-eyed looks. | | eyeScale | number | 1 | Size scale multiplier applied to the eyes. | | gazeRange | number | 1 | Multiplier for automatic gaze drift range (set to 0 to lock gaze forward). | | blinkTrigger | number | 0 | Numeric trigger that forces an instant blink whenever incremented. | | frozenAt | number | undefined | Freezes animation state at a specific time in seconds (useful for SSR & previews). |

🎨 Catalog

Pass "all" on shape, expression, or backgroundStyle to pick from the seed. Omit the prop (or pass a specific id) for the defaults below.

Shapes (21)

circle • pebble • squircle • capsule • triangle • hexagon • cloud • drop • square • pentagon • octagon • star • flower • cat • ghost • ufo • bot • alien • lion • monkey • mecha

Expressions (22)

neutral • happy • sad • excited • angry • loving • surprised • laughing • scared • suspicious • confused • curious • proud • shy • bored • sleepy • crazy • determined • guilty • amazed • doubtful • attentive

Background Styles (6)

solid • taygeta • celaeno • alcyone • maia • merope

🧰 Utilities Included

• createAvatar(seed: string, options?: SquishOptions): string | SquishJson
  Generates a complete SVG string (default) or a structured JSON object (format: "json") containing the rendered SVG, ready-to-use Data URI, and full geometric layout metadata.

• resolveShape / resolveExpression / resolveBackgroundStyle
  Same contract as resolveVariant in @usespaceui/avatars: omit → default, exact id → that id, "all" → deterministic pick from the seed.

• resolveLayout(seed: string, options?: SquishOptions): SquishLayout
  Executes the deterministic geometric solver to compute transformed eye capsules, body bezier paths, and palettes without rendering.

• renderLayout(layout: SquishLayout, options?: SquishOptions): string
  Serializes a computed SquishLayout object into a lightweight SVG document.

• SquishEngine
  Stateful animation class that powers fluid morphs, gaze physics calculations, and timeline orchestration.

📦 Related Packages

| Package | Description | | :----------------------------------------------------------------- | :---------------------------------------------------------- | | @usespaceui/avatars | Classic generative SVG avatar engine with multiple families | | @usespaceui/gradients | Procedural CSS & SVG gradient generator | | @usespaceui/sounds | UI sound effects and audio interactions | | @usespaceui/squircle | iOS & Figma style continuous curvature squircles |

🪪 License

MIT — Free for personal and commercial projects.

📚 Resources

• 🔍 Interactive Studio & Playground
• 📖 Space UI Documentation
• 🌍 Space UI Community

🛠 Maintenance

If you discover a bug or have a feature request, please open an issue on GitHub.