Deterministic, cute SVG avatars from a name — published on npm.
Give Blobbies a name and it takes the first two letters — the eyes — and builds a little blobby character around them: a flat-colored blob, a dark backdrop, a mouth and optional blush.
Same input → same avatar, forever. No gradients, no filters, no Math.random —
every decision comes from a seeded hash of the name. The core is zero
dependencies, the React bindings depend only on the core, and one avatar is
about 1.4 KB of SVG.
A small set of packages, and you only ship the one you use:
| Package | What it is | Install |
|---|---|---|
blobbies |
Renderer, hash, glyphs, motion runtime, CLI. Framework-agnostic. | npm i blobbies |
@blobbies/react |
<Avatar>, the <AvatarPicker>, and React hooks. |
npm i @blobbies/react |
@blobbies/vue |
<Avatar>, the <AvatarPicker>, and a composable for your own layout. |
npm i @blobbies/vue |
@blobbies/svelte |
<Avatar>, the <AvatarPicker>, and a rune module for your own layout. |
npm i @blobbies/svelte |
@blobbies/element |
<blobbies-avatar> — a web component that works in any framework. |
npm i @blobbies/element |
@blobbies/react-native |
<Avatar> for React Native and Expo, over react-native-svg. |
npm i @blobbies/react-native |
import { renderAvatarSvg } from 'blobbies';
renderAvatarSvg('Sourav Nanda'); // → "<svg …>"import { Avatar } from '@blobbies/react';
<Avatar name="Sourav Nanda" animate="all" />;npm i blobbies # framework-agnostic core
npm i @blobbies/react # React bindings (peer: react >= 18)
npm i @blobbies/vue # Vue bindings (peer: vue >= 3.3)
npm i @blobbies/svelte # Svelte bindings (peer: svelte >= 5)Every binding is fully typed and declares sideEffects: false so bundlers drop
whatever you do not import. React, Vue and React Native ship ESM + CJS; Svelte
ships its component as source, which your bundler compiles — that is what lets
it server-render. blobbies/motion is a separate entry point, so static users
never download the animation runtime.
The core is a pure function, so it also ships as a command. Useful in a script, a design tool, or an AI agent:
npx blobbies render "Sourav Nanda" > avatar.svg
npx blobbies render "Ira" --expression wink --color sky --animate all
npx blobbies shapes # list the egg shapes
npx blobbies manifest # the machine-readable capability dataFour ways in. Pick the one that matches where the avatar lives.
1. An SVG string (any framework, or none)
import { renderAvatarSvg } from 'blobbies';
el.innerHTML = renderAvatarSvg('Sourav Nanda');2. A data URI (for <img>, CSS, email, anywhere a URL is needed)
import { avatarDataUri } from 'blobbies';
img.src = avatarDataUri('Sourav Nanda');3. React
import { Avatar } from '@blobbies/react';
<Avatar name="Sourav Nanda" size={40} animate="all" />;4. Just the initials
import { getInitials } from 'blobbies';
getInitials('Sourav Nanda'); // "SN"Everything is pure and SSR-safe — nothing touches window or document at
import time. renderAvatarSvg returns the same string on the server and the
client, so the markup hydrates byte-for-byte. useAvatarMotion attaches the
cursor runtime in an effect, so it is a no-op during SSR.
getInitials(name)→ the two eye characters ("Sourav Nanda"→"SN","Ira"→"IR","@souravinsights"→"SO", empty/odd input →"?"). Emoji and punctuation are ignored; non-Latin letters are kept.- The name is hashed with cyrb53 and fed into a mulberry32 PRNG.
- The seeded PRNG picks the blob color, shape, rotation, mouth, blush and the backdrop nudge — deterministically.
A–Z/0–9eyes are hand-authored, stroke-based SVG paths on a 24×24 grid with flat (butt) caps and a heavy-grotesque weight — no fonts. Characters outside that set fall back to a bold<text>element.- Composition: the dark disk is the outer, complete circle. The coloured
layer is a soft egg whose curve was fitted to the reference width
profile, and it is clipped to the disk with a seed-scoped
clipPath— so it can never poke out of the circle or be clipped flat by the viewBox.
The avatar is rendered as independent layers so each can be animated on its own:
<defs><clipPath id="bb-…-c"><circle cx="50" cy="50" r="50"/></clipPath></defs>
<g class="bb-backdrop">…</g> <!-- dark disk (outer circle) -->
<g class="bb-blob">…</g> <!-- coloured egg + blush, clipped to the disk -->
<g class="bb-eyes">…</g> <!-- both eyes, each in a .bb-eye -->
<g class="bb-mouth">…</g> <!-- mouth -->Every class is scoped with a seed-derived prefix (bb-…), so any number of
avatars can share a page without their styles touching.
All animation is opt-in (animate defaults to false). There are two
runtimes, and they have different constraints.
renderAvatarSvg(name, { animate: 'blink' }) embeds a tiny, seed-scoped
<style> block that scales each .bb-eye vertically (scaleY(1 → 0.1 → 1)).
Timing comes from the seeded hash, so avatars never blink in sync, and ~1 in 4
blinks is a quick double blink. It is disabled under
@media (prefers-reduced-motion: reduce).
Because it is plain CSS inside the SVG, blink works everywhere, including:
<img src="data:image/svg+xml,…" /> <!-- ✅ blinks -->Use avatarDataUri(name, { animate: 'blink' }) to get that data URI.
import { attachAvatarMotion } from 'blobbies/motion';
const cleanup = attachAvatarMotion(svgElement, { followRange: 6, smoothing: 0.15 });
// …later
cleanup();- One shared
pointermovelistener per target (usually justwindow) and onerequestAnimationFrameloop for every attached avatar. - For each avatar it computes the vector from its centre to the pointer, clamps
it to
followRange(in viewBox units) and writes--look-x/--look-yCSS variables on the<svg>. The DOM is never re-rendered. - Only the facial features move — the colored blob and the dark disk stay fixed in place. Eyes track the pointer at 100% of the range and the mouth at 70%, so the face shifts subtly without the body ever sliding around.
- Motion is smoothed with a lerp; after
idleTimeoutms of no pointer movement it eases back to centre. - Pauses when the tab is hidden (
visibilitychange) and when the avatar is off-screen (IntersectionObserver).
Cursor follow requires inline SVG. It cannot work inside
<img src="data:image/svg+xml,…">, because scripts can't reach into an image's DOM. Use the React<Avatar>component (or your own inline SVG) for follow.
wink (wink on click), glance (periodic random glance when idle) and
surprise (a small pop when the pointer gets very close).
Colors, shapes and moods are set by name, not by index. The trait props read as the things they are — a colour, a mood, an egg — which is what a custom UI wants to put in front of a person.
import { Avatar, COLORS } from '@blobbies/react';
<Avatar name="Sourav Nanda" color={COLORS.sky} expression="smirk" shape="round" blush />;renderAvatarSvg('Sourav Nanda', { color: COLORS.sky, expression: 'smirk', shape: 'round' });| Trait | Values |
|---|---|
color |
Any CSS colour, or COLORS.sky for the built-in set |
shape |
'tall' | 'wide' | 'squat' | 'round' | 'mid' |
expression |
'smile' | 'smirk' | … — every mood in EXPRESSIONS |
blush |
boolean |
tilt |
number (degrees) |
backdrop |
number (0..3) |
A brand palette is just an array of hex values. The seeded hash picks from
whatever you give it, and color still overrides a single avatar.
<Avatar name="Sourav Nanda" color="#0FA3B1" />
<Avatar name="Sourav Nanda" palette={['#0FA3B1', '#FFD166', '#EF476F']} />variant reseeds only the body. The eyes still come from the name, so the same
person can have many looks without ever becoming someone else.
<Avatar name="Sourav Nanda" variant={3} />renderAvatarBody returns the inner markup plus the resolved metadata (letters,
seed prefix, blink timing) so you can drop Blobbies into your own SVG shell.
import { renderAvatarBody } from 'blobbies';
const { body, prefix, letters, blink } = renderAvatarBody('Sourav Nanda');@blobbies/react ships a ready-made look map. Columns are colours, rows are
moods, and the map wraps in both directions, so it never ends. Every face is a
version of the same person — the eyes come from name and never change.
Drag or swipe to pan, trackpad to glide, arrow keys to move. Hovering brings a face forward; cells shrink and fade with distance from it, so the edges dissolve without ever clipping the chosen face.
The map sizes its own grid to whatever box it is given — a full settings page, a 380px popover, or a phone dialog — so it never clips its edge faces. Drop the same component into a dialog, an inline settings row, a popover or a sign-up step.
import { Avatar, AvatarPicker } from '@blobbies/react';
<AvatarPicker
name="Sourav Nanda"
defaultValue={user.look}
onSave={(look) => updateUser({ look })}
onCancel={() => setOpen(false)}
/>;
// The saved look is the same props you pass to <Avatar>.
<Avatar name="Sourav Nanda" {...saved} size={40} />;| Prop | Default | What it does |
|---|---|---|
name |
required | The person's name — the eyes every look shares. |
defaultValue |
seeded | The look to open on (AvatarOptions). Read once. |
palette |
PALETTE |
The colours the map offers — pass your own. |
onChange |
– | Called with the current look as it changes. |
onSave |
– | Called with the look when Save is pressed. |
onCancel |
– | Shows Cancel and calls this. |
title / description |
'Choose an avatar' / … |
Header copy. Pass '' to hide. |
saveLabel |
'Save' |
Save button label. |
spotlight |
true |
Start with the depth-of-field spotlight on. The picker also ships a Spotlight toggle. |
className |
– | Added to the root. |
unstyled |
false |
Skip the panel styles; style the parts yourself. |
The panel is themed entirely with CSS variables. Set them on the root (or an ancestor) and the picker follows your product.
| Variable | |
|---|---|
--bb-picker-panel |
Surface background |
--bb-picker-ink |
Primary text and marks |
--bb-picker-muted |
Secondary text |
--bb-picker-line |
Borders and dividers |
--bb-picker-accent |
Save button background |
--bb-picker-accent-ink |
Save button text |
--bb-picker-radius |
Panel corner radius |
--bb-picker-shadow |
Panel shadow |
--bb-picker-spring |
The spring curve for pops |
--bb-picker-fade |
The short curve for colour |
.brand-picker {
--bb-picker-panel: #101014;
--bb-picker-accent: #ffd43b;
--bb-picker-accent-ink: #1c1c1c;
}The preset is only a composition of parts. Import the parts, keep the state, and
lay them out however your product needs. Every part carries a data-part
attribute (root, header, title, description, surface, preview,
mood, blush, spotlight, reset, cancel, save, footer) for your own
CSS hooks.
import {
AvatarPickerRoot,
AvatarPickerSurface,
AvatarPickerPreview,
AvatarPickerMood,
AvatarPickerBlush,
AvatarPickerSpotlight,
AvatarPickerReset,
AvatarPickerSave,
AvatarPickerCancel,
useAvatarPicker,
} from '@blobbies/react';
<AvatarPickerRoot name={user.name} defaultValue={user.look} onSave={save} unstyled>
<AvatarPickerPreview size={72} />
<AvatarPickerSurface />
<AvatarPickerMood />
<AvatarPickerBlush />
<AvatarPickerSpotlight />
<AvatarPickerReset />
<AvatarPickerSave>Keep it</AvatarPickerSave>
<AvatarPickerCancel />
</AvatarPickerRoot>;useAvatarPicker() exposes the state when you want to render your own controls:
const {
value, changed, blush, spotlight, palette,
expressionName, nextExpression, previousExpression,
toggleBlush, toggleSpotlight, reset, save, cancel, hasCancel,
} = useAvatarPicker();The same options are accepted by the core renderer and the React component.
type AvatarOptions = {
// Look — each defaults to a value seeded from the name
color?: string // any CSS colour, e.g. COLORS.sky
shape?: 'tall' | 'wide' | 'squat' | 'round' | 'mid'
expression?: 'smile' | 'smirk' | … // EXPRESSIONS
blush?: boolean
tilt?: number // degrees
backdrop?: number // 0..3
variant?: number // 0 — same eyes, another look
palette?: readonly string[] // the built-in palette
// Render
size?: number | string // 48
rounded?: boolean // false
className?: string
title?: boolean // false
// Motion
animate?: boolean | 'blink' | 'follow' | 'all' // false
blink?: boolean // true when animated
blinkInterval?: [number, number] // [2500, 6000]
follow?: boolean // true when animated
followRange?: number // 6
followTarget?: 'window' | Element // 'window'
smoothing?: number // 0.15
idleTimeout?: number // 2500
paused?: boolean // false
respectReducedMotion?: boolean // true
wink?: boolean // false
glance?: boolean // false
surprise?: boolean // false
};| Export | Description |
|---|---|
getInitials(name) |
The two eye characters ("SN"). |
renderAvatarSvg(name, options?) |
Full standalone SVG string. |
renderAvatarBody(name, options?) |
Inner markup + resolved metadata (for wrappers). |
avatarDataUri(name, options?) |
data:image/svg+xml,… (static / blink-only). |
attachAvatarMotion(svg, options?) |
From blobbies/motion. Returns a cleanup fn. |
resolveAvatar(name, options?) |
Every seeded decision, without rendering. |
COLORS |
The built-in palette by name (COLORS.sky, …). |
PALETTE |
The same colours, in canonical order. |
BACKDROP_COLOR / INK_COLOR / BLUSH_COLOR |
The fixed layer colours. |
EXPRESSIONS / SHAPES |
Every mood and egg shape, by name. |
EXPRESSION_NAMES |
Display names for every expression, for labels. |
EXPRESSION_COUNT / SHAPE_COUNT |
How many expressions and egg shapes there are. |
LETTER_PATHS / LETTER_BOX / STROKE_WIDTH / INK_WIDTH / hasLetterPath |
The hand-drawn glyph geometry. |
hashString / cyrb53 / mulberry32 / createRng |
The deterministic seeding primitives. |
| Export | Description |
|---|---|
<Avatar name …options /> |
Inline, SSR-safe SVG (role="img", aria-label). |
<AvatarPicker name … /> |
The preset look map. |
AvatarPickerRoot + parts |
Build your own layout (see above). |
AvatarPickerPreview |
The chosen face, for layouts that show it outside the map. |
useAvatarPicker() |
The picker state, for custom controls. |
useAvatarMotion(ref, options?) |
Attach motion to your own SVG. |
AvatarPickerProps, AvatarPickerState, AvatarProps, … |
The public types. |
useAvatarMotion keeps one stable options object and only re-attaches when the
follow target or enabled state changes — pointer movement never triggers a
re-render.
Flat, bright and friendly. Every colour is verified to read well with the
#1c1c1c eyes and #2f2f2f backdrop, on light and dark pages.
| Name | Hex | Name | Hex | Name | Hex | ||
|---|---|---|---|---|---|---|---|
| yellow | #FFD43B |
green | #5FD068 |
sky | #6CC8FF |
||
| coral | #FF7B7B |
lavender | #B79CFF |
peach | #FFB074 |
||
| mint | #5EE0C0 |
pink | #FF8FC7 |
orange | #FFA64D |
This is a pnpm workspace of published packages and the site.
packages/core blobbies – hash, initials, SVG, animation runtimes
packages/react @blobbies/react – <Avatar>, <AvatarPicker>, hooks
packages/vue @blobbies/vue – <Avatar>, <AvatarPicker>
packages/svelte @blobbies/svelte – <Avatar>, <AvatarPicker>
packages/element @blobbies/element – <blobbies-avatar> web component
packages/react-native @blobbies/react-native – <Avatar> over react-native-svg
apps/site blobbies-site – Vite + React landing page
examples/with-react blobbies-example-react – a React app, picker included
examples/with-vue blobbies-example-vue – a Vue app, picker included
examples/with-svelte blobbies-example-svelte – a Svelte app, picker included
examples/with-html blobbies-example-html – one tag, no framework
pnpm install
pnpm dev # the site at http://localhost:5173
pnpm test # vitest across packages
pnpm build # tsup build of both packages
pnpm typecheck # tsc across the workspaceTwo files are generated from the code and checked by a test, so they can never go stale. Never edit them by hand — change the source, run the script, commit both:
pnpm --filter blobbies export:fixtures # fixtures/avatar-conformance.json
pnpm --filter blobbies export:manifest # manifest.jsonPlanning a new framework or platform? Read docs/PLATFORMS.md.
Working with an AI agent? Point it at AGENTS.md and llms.txt.
Preview sheets (generated, then opened in a browser):
pnpm preview:letters # apps/site/preview/letters.html
pnpm preview:avatars # apps/site/preview/avatars.html
pnpm preview:blink # apps/site/preview/blink-img.htmlMIT © Blobbies contributors
