fn-ui-avatars vs Raw API

Try it and see the difference.

Native API (UI-Avatars)

Native API Avatar

❌ Using background=random makes colors change unpredictably on every 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

John Doe

✅ 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');

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
GitHubnpm

fn-ui-avatars-react

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

npm install fn-ui-avatars-react
GitHubnpm

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" />
John DoeLight Name

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 / OptionTypeDefaultDescription
namestringRequiredThe name used to generate initials and deterministic background color.
sizenumber192Avatar image size in pixels.
fontSizenumber0.33Font size ratio (0.1 – 1).
lengthnumber2Number of initials to display.
roundedbooleantrueRenders a circular avatar if true, square if false.
colorstring'fff'Text color hex (without #). Automatically outputs 'fff' or '000' for best contrast.
format'svg' | 'png''svg'The image format returned by the API.
baseUrlstring'https://ui-avatars.com/api/'Custom API base URL if you are hosting your own instance.