Introduction
Most apps need avatars. You might need them for user profiles, comments, chat messages, team dashboards, or bot identities. The problem is that setting up profile image uploads early on can feel like too much work. You need storage, validation, fallback states, and extra UI. Facehash gives you a much simpler starting point. It generates a unique avatar face from any string, right inside your app.
Facehash is a React component built for generating consistent avatar faces from values like usernames, emails, or IDs. The same input always gives you the same output. That makes it useful when you want avatars that look stable across sessions without depending on an external service or storing generated images yourself. It also works with setups like Next.js, Vite, and Remix.
Why Facehash is useful
A lot of avatar solutions are either too heavy or require extra setup. Facehash keeps things simple. You pass a string, and it gives you a face. There are no API calls involved, no stored avatar files, and no random output changing between sessions. That makes it a practical option for early stage products, internal tools, and side projects where you want the UI to look complete without building a full image upload flow.
It is also a good fit for more than just user accounts. Facehash works well for chat apps, comment sections, team directories, placeholder avatars, bot identities, and AI agents. If your product needs lightweight visual identity, this is a clean way to do it.
How to set up Facehash
Getting started is simple. Install the package first:
npm install facehash
Then import the component and pass a name prop:
import { Facehash } from "facehash";
export default function UserAvatar() {
return <Facehash name="harshal" size={48} />;
}
That is enough to render a face for a given value. The library is built for React and the basic usage is intentionally small, which makes it easy to test in an existing project without changing much code.
Useful props you should know
The main prop is name, which decides the generated face. This can be a username, email, UUID, or any other stable string. Facehash also supports size for controlling avatar dimensions and colors if you want to use your own palette instead of the default one.
You can also change the look of the avatar with intensity3d, variant, showInitial, and enableBlink. So if you want a cleaner flat style, a more playful style, or something closer to your brand colors, you have enough control without turning the component into a whole design system on its own.
Another useful prop is className, which lets you style the component with your existing CSS or Tailwind classes. There is also an onRenderMouth option for custom mouth rendering, which can be useful if you want loading states or a slightly more playful avatar treatment in your UI.
import { Facehash } from "facehash";
export default function FacehashPropsExample() {
return (
<Facehash
name="agent-47"
size={72}
variant="gradient"
intensity3d="dramatic"
interactive
showInitial={false}
colors={["#264653", "#2a9d8f", "#e9c46a", "#f4a261"]}
colorClasses={[
"bg-emerald-600",
"bg-sky-600",
"bg-amber-500",
"bg-rose-500",
]}
gradientOverlayClass="bg-[radial-gradient(circle_at_top,rgba(255,255,255,0.28),transparent_62%)]"
enableBlink
className="rounded-2xl text-stone-950 shadow-md"
onRenderMouth={() => (
<span className="flex items-center gap-1" aria-hidden>
<span className="size-1 rounded-full bg-current" />
<span className="size-1 rounded-full bg-current" />
<span className="size-1 rounded-full bg-current" />
</span>
)}
/>
);
}
Generate avatar image URLs in Next.js
One useful part of Facehash is that it is not limited to rendering inside a React component. If you are using Next.js, you can expose a route that generates avatar images as URLs. This is useful for profile images, OG image flows, favicons, browser UI, or anywhere else you need a stable avatar image path instead of a rendered component.
Here is the basic route setup:
// app/api/avatar/route.ts
import { toFacehashHandler } from "facehash/next";
export const { GET } = toFacehashHandler();
After that, you can use the route like this:
<img src="/api/avatar?name=john" alt="John avatar" />
And if you want SVG output:
/api/avatar?name=john&format=svg&pose=front
This is a nice option when you need avatar images outside your React tree, such as emails or generated pages where a direct image URL is more useful. Facehash documents PNG output by default and raw SVG output for cases like icons and favicons.
A clean fallback for profile photos
Facehash also includes an avatar wrapper pattern with Avatar, AvatarImage, and AvatarFallback. This is useful when you want to show a real uploaded photo if it exists, but fall back to a generated Facehash avatar when the image is missing or fails to load.
That makes it easier to keep your UI consistent. Instead of showing broken image icons or plain initials, you can always fall back to something that still looks designed. For many apps, that is a much better default experience.
import { Avatar, AvatarImage, AvatarFallback } from "facehash";
<Avatar>
<AvatarImage src="/photo.jpg" />
<AvatarFallback name="anthony" />
</Avatar>;
Where Facehash fits best
Facehash is most useful when you want avatars without building extra infrastructure too early. It fits well in SaaS dashboards, internal tools, chat products, comment systems, early stage startups, and any app where users may not upload profile pictures right away.
It is also a good fit when consistency matters. Because the output is deterministic, the same identifier always maps to the same face. That small detail makes the product feel more stable and easier to recognize, especially in places where users or bots appear often.
Final thoughts
Facehash solves a very common UI problem in a simple way. It gives you unique avatar faces from any string, works in modern React setups, supports image URL generation for Next.js, and gives you enough customization to make the avatars feel at home in your product. It is also accessible by default, fully typed, and designed to work without external assets.
If you are building a product and want a quick way to add personality to user accounts, bots, or placeholder states, Facehash is worth trying.


Top comments (0)