boring-avatars

Boring Avatars is a React library that generates crisp, scalable SVG avatars deterministically from a name, username, or email string — no image uploads, external avatar service, or network request required. Six visual variants (marble, beam, pixel, sunset, ring, and bauhaus) turn the same hashed input into a fixed, colorful pattern, so a given user’s avatar stays consistent across sessions and devices without ever being stored.

Each variant is implemented as its own lightweight SVG-rendering component, and picking one is a single prop away — making it a drop-in placeholder avatar for user lists, chat interfaces, dashboards, and any UI that needs a default profile picture. Because it renders pure inline SVG, avatars stay crisp at any size and produce zero image requests, cutting load time and avoiding dependence on third-party avatar generation services like Gravatar.

What You Get

• Six SVG avatar variants — marble, beam, pixel, sunset, ring, and bauhaus — selectable via a single variant prop
• Deterministic generation from any string (name, username, or email) so the same input always renders the same avatar
• A single <Avatar> React component with simple props for size, color palette, square/round shape, and accessible title text
• Pure inline SVG output with zero network requests or external avatar-service dependency

Common Use Cases

• Placeholder profile pictures for user lists and directories when no photo has been uploaded
• Chat and messaging UI avatars that need to render instantly without waiting on an image fetch
• Team and member avatars in dashboards and admin panels where a lightweight, brand-colorable visual is preferred over stock icons
• Anonymous or guest user avatars in comment sections and collaborative apps

Under The Hood

Architecture The library is a small, flat modular design: src/lib/index.tsx exports a single Avatar component that dispatches to one of six per-variant SVG components (avatar-marble.tsx, avatar-beam.tsx, avatar-pixel.tsx, avatar-sunset.tsx, avatar-ring.tsx, avatar-bauhaus.tsx) via an AVATAR_VARIANTS lookup map keyed by the variant prop, with legacy aliases (geometric → beam, abstract → bauhaus) preserved for backward compatibility. Each variant component is self-contained: it derives a numeric hash from the input string via utilities.ts’s hashCode, then feeds that hash through getUnit/getRandomColor/getDigit/getBoolean helpers to deterministically pick colors, translations, rotations, and scales for a small number of SVG shape elements, so there is no shared render tree or state beyond the per-call prop values — a pure function-in, SVG-out design with no internal state, context, or class hierarchy. The src/demo/ folder hosts a Vite-based playground app for local development, cleanly separated from the published src/lib/ surface; because every variant leans on the same hashCode/utility module, a change to that shared hashing logic would shift the visual output of all six variants and any existing embed relying on a stable avatar-for-name mapping.

Tech Stack TypeScript throughout (over 90% of the codebase), built with Vite and vite-plugin-dts to emit both a JS bundle and .d.ts declarations to dist/, with tsc run against a dedicated tsconfig.lib.json as a type-check step ahead of the Vite build. The only runtime peer dependencies are react and react-dom (>=18), so the published library itself ships with zero non-React runtime dependencies. Dev-only dependencies (nice-color-palettes, react-color, styled-components) power the demo/playground UI, not the library itself. ESLint 9 with typescript-eslint, eslint-plugin-react-hooks, and eslint-plugin-react-refresh handles linting. There is no backend, database, or third-party integration — this is a pure client-side rendering library targeting React 18+/19 apps.

Code Quality No test files or testing framework exist anywhere in the repository — correctness relies entirely on manual and visual verification via the demo playground, which is a notable gap for a library this widely depended on. ESLint is configured with recommended and TypeScript-aware rules, but no CI workflow actually runs lint or build checks; the only GitHub Actions workflow present is a stale-issue bot. Naming is consistent (avatar-<variant>.tsx files, camelCase utilities) and types are used throughout via a shared AvatarProps type, but explicit error handling is essentially absent — helper functions like the hex-to-contrast conversion assume well-formed input and would silently produce NaN rather than validate or throw.

API Design The public API is a single default-exported <Avatar> component with a small, well-named prop set (name, colors, variant, size, square, title) and sensible defaults for every one of them, so <Avatar name="x" /> works with zero configuration — genuinely low-boilerplate to adopt. Prop naming mirrors familiar HTML/SVG conventions rather than inventing bespoke terms, and six visually distinct styles are exposed through one string enum rather than six separate components, while backward-compatible aliases (geometric, abstract) show deliberate care not to break existing consumers across renames. Documentation is limited to a single README prop table plus inline usage snippets — there is no dedicated docs site, Storybook, or per-variant customization guide, and prop-level JSDoc is absent from the source, so IDE autocomplete surfaces types without descriptions.