notion-avatar: a self-hostable Notion-style avatar maker with AI generation

What notion-avatar solves, and who it is for

Notion's own avatar picker gives you a fixed set of faces and no way to remix them. notion-avatar takes that visual language, the flat line-drawn face with simple eyes, brows and hair, and turns it into a combinatorial builder. The README lists the part inventory: 16 face shapes, 14 noses, 20 mouths, 14 eyes, 16 eyebrows, 14 glasses, 58 hairstyles, 16 beards, 13 facial details and 14 accessories. Mixing those gives a very large number of distinct faces from a small asset set, which is the whole point of the design.

The audience is narrow but real. It fits a team that wants a consistent set of illustrated avatars for internal tools, docs or a community, and does not want to commission illustrations or depend on a third-party avatar service. It also fits developers who want to read or fork a compact Next.js codebase that mixes SVG composition with an LLM call. It does not fit anyone who needs photographic avatars, brand-accurate mascots, or an avatar that has to survive outside this style.

How the avatar builder works: layered SVG parts plus a Gemini call

The repository is a Next.js app (next 13.0.0, react 18.2.0) written in TypeScript, with Tailwind for styling and next-i18next for the ten locales listed in the README. The avatar itself is not generated as a bitmap. It is assembled from individual SVG parts stored under public/, so a face is a selection of one item from each category. That is why the README can enumerate exact counts per category: each count is a folder of assets.

The AI path is separate from the part library. The package.json includes @google/genai at 1.34.0, and .env.example defines GEMINI_API_KEY. The README describes two AI features: transforming a photo into a Notion-style avatar, and generating avatars from a text description. Both route through Gemini rather than a local model, which means the AI features are an online dependency, not something the build gives you for free.

Around that core sit two optional services. @supabase/ssr and @supabase/supabase-js handle accounts and persistence, with a supabase/ directory in the repository, and stripe 20.1.0 plus four Stripe price IDs in .env.example suggest paid tiers or credit packs. For a self-hosted single-user deployment, those two are the parts you can leave unconfigured; the README does not describe a stripped-down mode, so how cleanly the app runs without them is something you would have to check in the code.

Installing notion-avatar and making a first avatar

The repository uses Yarn (yarn.lock is present, and .npmrc exists), and package.json defines the usual Next.js scripts. There is no published package to install; you clone the repository and run it locally. The README does not spell out an install sequence, so the commands below are taken from the scripts block in package.json.

yarn install
yarn dev

yarn install also runs the postinstall hook, which is husky install, so Git hooks are set up on install. yarn dev starts the Next.js dev server, which by default listens on port 3000, matching the NEXT_PUBLIC_URL value in .env.example. Open http://localhost:3000 and you should get the avatar editor.

Before the AI features work, copy .env.example to .env.local and fill in the keys you need. The minimum for AI generation is GEMINI_API_KEY; the Supabase and Stripe blocks are only needed if you want accounts and payments.

cp .env.example .env.local
# then edit .env.local
GEMINI_API_KEY=<Your_Gemini_API_Key>
NEXT_PUBLIC_URL=http://localhost:3000

The .env.example also carries NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_WEBHOOK_SECRET, and the three price IDs STRIPE_MONTHLY_PRICE_ID, STRIPE_YEARLY_PRICE_ID and STRIPE_CREDITS_PRICE_ID. Note that SUPABASE_SERVICE_ROLE_KEY bypasses row-level security, so it belongs on the server and nowhere near the client bundle.

For a production build, the scripts are the standard pair:

yarn build
yarn start

yarn build runs next build and yarn start runs next start. The project also ships yarn type-check (tsc) and yarn lint (eslint over src/**/*.+(ts|js|tsx)) if you want to verify a fork before deploying it.

The AI features are a paid, online dependency

The clearest limitation is that the headline feature is not self-contained. The part-based editor works offline once the assets are on disk, but photo-to-avatar and text-to-avatar both call Gemini through @google/genai, so they need a GEMINI_API_KEY and network access, and they are subject to whatever quota and pricing Google applies to that key. The README does not document rate limits, per-request cost, or what happens when the key is missing or the quota is exhausted. If your use case is generating a few hundred avatars in a batch, you are planning around an external service the project does not control.

There is also a privacy angle worth stating plainly. A photo-to-avatar feature means user photographs leave your infrastructure and go to Google. If you are deploying this inside an organisation where photos of staff are sensitive, that is a decision to make before rollout, not after. The README does not describe any local model option or any way to keep the image on your own servers.

Finally, the style is the constraint. Every output is a flat Notion-style face. If you need avatars that match a different illustration system, this project gives you no path to that beyond editing or replacing the SVG assets yourself, and the README does not document the asset format or naming conventions.

notion-avatar versus DiceBear or drawing the SVGs yourself

The closest comparison in approach is DiceBear, which also composes avatars from SVG parts and exposes them through an HTTP API and JavaScript libraries. The difference is where the work happens and what you get. DiceBear is avatar generation as a service or a library: you request an avatar by seed and get an image back, and you can call it from a backend or a build step. notion-avatar is a full application. It gives you a visual editor, a specific Notion-adjacent art style, and an AI path that DiceBear does not have, but it does not give you a documented API for generating avatars programmatically. If your requirement is "give every user in my database a deterministic avatar from their user ID", the library approach fits better. If your requirement is "let people design and download a Notion-style face", this project is the more direct fit.

The other alternative is simply using the hosted site at notion-avatar.app. That is the same codebase, run by the maintainer, with no build, no API key and no Supabase project. Self-hosting only makes sense when you need control: your own domain, your own data handling, custom assets, or an integration into an existing app. Otherwise the hosted version is strictly less work.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-06-06. There are no releases retrieved, so there is no versioned artifact to track; you follow the main branch or pin a commit. The dependency list mixes recent packages (@google/genai 1.34.0, @supabase/supabase-js 2.89.0, @tanstack/react-query 5.90.14) with older ones (next 13.0.0, react 18.2.0, dayjs 1.10.7, sharp 0.32.6). Next 13 is several major versions behind current Next.js, so a fork that wants to stay current is looking at a framework upgrade, not a patch. The presence of renovate.json suggests dependency updates are at least configured, though the README says nothing about a support policy or a release cadence.

On licensing: package.json declares MIT, and the README states the illustration assets are licensed under CC0, with the pack credited to Felix Wong and linked as "Noto avatar" on Gumroad. MIT covers the code and CC0 places the artwork effectively in the public domain, which is unusually permissive for an avatar project and removes the attribution burden that many asset packs carry. This is a description of what the files state, not legal advice; if you redistribute the assets inside a commercial product, read LICENSE.md and the CC0 text yourself rather than relying on this summary.

Editorial conclusion

Adopt it if you want a Notion-style avatar builder you control, can supply a GEMINI_API_KEY, and are willing to run Supabase and Stripe only if you need accounts and paid credits. Skip it if you just want a quick avatar for yourself, since the hosted site at notion-avatar.app already does that without a build step, and skip it if you need an unauthenticated avatar API, because the README documents none. Before committing, check that the 16 face shapes, 58 hairstyles and other part counts in the README still match the assets under public/, and confirm which environment variables the code actually reads.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Mayandev/notion-avatar on GitHub
4. Project website
5. README