🐻 MugBear

Avatar Playground for Developers

Generate consistent avatars from any name.
One package · Three providers · Zero config · No API key

🎮 Live Playground  ·  📦 npm Package  ·  🐛 Report Issue

---

See it in action

DiceBear styles

RoboHash

UI Avatars

---

Install

npm install mugbear

pnpm add mugbear

yarn add mugbear

---

What is MugBear?

MugBear is a free open source avatar toolkit for developers.
It wraps three of the best free avatar providers — DiceBear, UI Avatars, and RoboHash — into one clean package with TypeScript support, React components, and zero configuration.

Same name → Same avatar. Always. No image storage needed.

---

Usage

Core — getAvatar()

import { getAvatar } from 'mugbear'

// DiceBear — initials (like Gmail)
const url = getAvatar('John Doe', { provider: 'dicebear', style: 'initials' })

// DiceBear — cartoon
const url = getAvatar('John Doe', { provider: 'dicebear', style: 'avataaars' })

// UI Avatars
const url = getAvatar('John Doe', { provider: 'ui-avatars', rounded: true })

// RoboHash — robots
const url = getAvatar('John Doe', { provider: 'robohash' })

Shorthand Helpers

import { initialsAvatar, cartoonAvatar, robotAvatar, pixelAvatar, getAllAvatars } from 'mugbear'

initialsAvatar('John Doe')   // → DiceBear initials URL
cartoonAvatar('John Doe')    // → DiceBear avataaars URL
robotAvatar('John Doe')      // → RoboHash URL
pixelAvatar('John Doe')      // → DiceBear pixel-art URL

// Get all providers at once
const all = getAllAvatars('John Doe')
// → { initials, cartoon, robot, pixel, notionists, thumbs, uiAvatars }

React Component

import { MugBearAvatar, AvatarWithFallback } from 'mugbear/react'

// Basic
<MugBearAvatar name="John Doe" size={64} />

// With provider + style
<MugBearAvatar
  name="John Doe"
  provider="dicebear"
  style="avataaars"
  size={128}
  shape="circle"
/>

// With automatic fallback (shows initials if API fails)
<AvatarWithFallback name="John Doe" size={64} />

---

API Reference

getAvatar(name, options)

Option	Type	Default	Description
provider	'dicebear' | 'ui-avatars' | 'robohash'	required	Which provider to use
style	DiceBearStyle	'initials'	DiceBear style (dicebear only)
size	number	128	Avatar size in px
rounded	boolean	false	Rounded corners (ui-avatars only)
shape	'circle' | 'square'	'circle'	Shape of avatar

DiceBear Styles

Style	Preview
initials
avataaars
notionists
thumbs
bottts
micah
pixel-art
lorelei
adventurer
croodles
fun-emoji
identicon

---

How It Works

MugBear uses deterministic seeding — the same name always returns the same avatar. No image uploads, no storage, no database.

'John Doe' → https://api.dicebear.com/7.x/initials/svg?seed=John%20Doe
                                                         ↑
                                              same input = same output

---

Providers

Provider	Styles	Format	Free	Link
DiceBear	30+ SVG styles	SVG	✅	dicebear.com
UI Avatars	Initials-based	SVG/PNG	✅	ui-avatars.com
RoboHash	Robots & monsters	PNG	✅	robohash.org

---

Works With

Use the Copy AI Prompt button on mugbear.vercel.app to get a ready-to-use prompt for any AI coding tool:

Claude Code   Cursor   Windsurf   GitHub Copilot   Bolt   Lovable   VS Code   Antigravity

---

Repo Structure

mugbear/
├── src/
│   ├── index.ts        ← core getAvatar() + helpers
│   └── react.tsx       ← React components
├── dist/               ← built output (ESM + CJS + types)
├── apps/
│   └── web/            ← mugbear.vercel.app
├── package.json
└── README.md

---

Contributing

PRs are welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create your branch: git checkout -b feature/your-feature
3. Commit: git commit -m 'add: your feature'
4. Push: git push origin feature/your-feature
5. Open a Pull Request

---

MIT License © azmaldev

⭐ Star on GitHub — if MugBear saved you time!