fn-ui-avatars vs Raw API

Type a name to see the chaotic random colors of the raw API vs our deterministic ecosystem.

Enter a first and last name:

Native API (UI-Avatars)

❌ Using background=random makes colors change unpredictably on every keystroke/render for the same user.

❌ Causes inconsistent avatars for the same user across different devices or sessions.

<img src="https://ui-avatars.com/api/?name=..." />

fn-ui-avatars

The Ecosystem

✅ Deterministic colors (John Doe always gets the exact same color).

✅ Smart contrast (Text adapts to the background).

✅ Framework agnostic core + React wrapper.

getAvatarUrl('John Doe');

Real World Context using fn-ui-avatars

Context 1: User Table

John Doeuser@example.com

Context 2: Chat Bubble

John Doe

Notice how my color matches the table perfectly?

Documentation

1. Choose your package

fn-ui-avatars

The core math engine. Zero dependencies. Use it in Vanilla JS, Vue, Svelte, Node, or via CDN.

npm install fn-ui-avatars

GitHub npm

fn-ui-avatars-react

The official React wrapper. Ready-to-use component with seamless Tailwind CSS support.

npm install fn-ui-avatars-react

GitHub npm

2. Usage

Vanilla JS (Core Package)

import { getAvatarUrl } from 'fn-ui-avatars';

const url = getAvatarUrl('Maria Silva');
document.getElementById('avatar').src = url;

React / Next.js Component

import { Avatar } from 'fn-ui-avatars-react';

<Avatar name="John Doe" />
<Avatar name="Light Name" />

Custom Curated Palette

import { Avatar } from 'fn-ui-avatars-react';

<Avatar 
  name="Alice"
  palette={['#F87171', '#FCD34D', '#10B981', '#4A7BCC']} 
/>

<Avatar 
  name="Bob"
  palette={['#F87171', '#FCD34D', '#10B981', '#4A7BCC']} 
/>

3. API & Props Reference

Core API (Vanilla)

getAvatarUrl(name, options?)Returns the UI-Avatars URL string.
loadAvatars(selector?, options?)Scans the DOM and injects src attributes automatically.

React Wrapper

<Avatar name="John" {...options} />Renders a standard HTML <img> tag.
* Accepts all native image attributes like className, onClick, etc.

Configuration Options

These properties can be passed as an options object to the Core API, or directly as props to the React Component.

Prop / Option	Type	Default	Description
name	string	Required	The name used to generate initials and deterministic background color.
size	number	192	Avatar image size in pixels.
fontSize	number	0.33	Font size ratio (0.1 – 1).
length	number	2	Number of initials to display.
rounded	boolean	true	Renders a circular avatar if true, square if false.
color	string	'fff'	Custom text color (hex with or without #). Overrides the default Smart Contrast.
palette	string[]	[]	Array of custom hex colors to be used as the background. Picked deterministically.
format	'svg' \| 'png'	'svg'	The image format returned by the API.
baseUrl	string	'https://ui-avatars.com/api/'	Custom API base URL if you are hosting your own instance.