react-avatar-initials

A customizable, deterministic user avatar and initials generator for React with zero dependencies.

Installation

npm install react-avatar-initials

or with yarn:

yarn add react-avatar-initials

or with pnpm:

pnpm add react-avatar-initials

Quick Start

import React from 'react';
import Avatar from 'react-avatar-initials';

export default function App() {
  return (
    <div style={{ display: 'flex', gap: '12px' }}>
      {/* Generates deterministic pastel background from name */}
      <Avatar name="Sarah Connor" />

      {/* Modern gradient background */}
      <Avatar name="John Doe" colorMode="gradient" />

      {/* With custom size and status indicator */}
      <Avatar name="Alex Morgan" size={48} status="online" />

      {/* Image with automatic initials fallback on error */}
      <Avatar
        name="Bruce Wayne"
        src="https://example.com/avatar.jpg"
        size={48}
      />
    </div>
  );
}

Features & Usage

1. Shape Variants

// Circle (default)
<Avatar name="Jane Doe" variant="circle" />

// Square
<Avatar name="Jane Doe" variant="square" />

// Rounded corners
<Avatar name="Jane Doe" variant="rounded" borderRadius={10} />

2. Color Themes

// Pastel colors (default)
<Avatar name="Jane Doe" colorMode="pastel" />

// Vibrant CSS gradients
<Avatar name="Jane Doe" colorMode="gradient" />

// Monochrome slate/dark
<Avatar name="Jane Doe" colorMode="monochrome" />

// Custom solid color
<Avatar name="Jane Doe" backgroundColor="#3b82f6" textColor="#ffffff" />

3. Status Indicators

<Avatar name="Alice" status="online" />
<Avatar name="Bob" status="busy" />
<Avatar name="Charlie" status="away" />
<Avatar name="Diana" status="offline" />

4. AvatarGroup

Stack multiple avatars with an automatic remainder indicator.

import { AvatarGroup, Avatar } from 'react-avatar-initials';

<AvatarGroup max={3}>
  <Avatar name="Emma Watson" />
  <Avatar name="Daniel Radcliffe" />
  <Avatar name="Rupert Grint" />
  <Avatar name="Tom Felton" />
</AvatarGroup>

5. useAvatar Hook

Compute initials and colors programmatically without rendering the component:

import { useAvatar } from 'react-avatar-initials';

const { initials, background, text } = useAvatar('John Doe', {
  colorMode: 'gradient',
});

Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | name | string | undefined | User name used to extract initials & pick colors | | src | string | undefined | Image URL (falls back to initials on load failure) | | size | number \| string | 40 | Width and height in pixels | | variant | 'circle' \| 'square' \| 'rounded' | 'circle' | Shape style | | borderRadius | number \| string | 8 | Corner radius when variant="rounded" | | colorMode | 'pastel' \| 'gradient' \| 'monochrome' \| 'custom' | 'pastel' | Color selection strategy | | backgroundColor | string | undefined | Custom background color override | | textColor | string | undefined | Custom text color override | | status | 'online' \| 'offline' \| 'busy' \| 'away' \| string | undefined | Status dot badge | | maxInitials | number | 2 | Number of initial letters (1, 2, or 3) | | border | string | undefined | Border stroke (e.g. '2px solid white') | | fontSize | number \| string | Auto | Custom font size override |

License

MIT