React Initials Avatar Generator

A lightweight, customizable React component for generating beautiful initials-based avatars. Perfect for user profiles, contact lists, and any application that needs elegant placeholder avatars.

Features

• 🎨 Fully customizable colors, sizes, and styles
• 🔤 Smart initials extraction from names
• 📦 Zero dependencies (except React)
• 🎯 Full TypeScript support with exported types
• ⚡ Lightweight and performant (~1.2KB gzipped)
• 🎭 Flexible styling options
• 📘 Complete type definitions included
• 🔧 Works with React 18+

Installation

npm install react-intials-avatar-generator

or

yarn add react-intials-avatar-generator

or

pnpm add react-intials-avatar-generator

Quick Start

import { InitialsAvatar } from 'react-intials-avatar-generator';

function App() {
  return (
    <div>
      {/* Basic usage */}
      <InitialsAvatar name="John Doe" />
      
      {/* With custom styling */}
      <InitialsAvatar 
        name="Jane Smith"
        styles={{
          size: 80,
          bgColor: "#10b981",
          textColor: "#ffffff"
        }}
      />
    </div>
  );
}

Props

Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | name | string | required | The full name to extract initials from | | styles | StyleProps | {} | Styling configuration object | | options | InitialOptions | {} | Options for initials extraction |

StyleProps

Configure the visual appearance of the avatar:

| Property | Type | Default | Description | |----------|------|---------|-------------| | size | number | 50 | Avatar size in pixels (width and height) | | radius | number \| string | "50%" | Border radius (use "50%" for circle, number for rounded square) | | bgColor | string | "#4f46e5" | Background color (any valid CSS color) | | textColor | string | "#ffffff" | Text color for initials | | fontFamily | string | "inherit" | Font family for the initials | | fontSize | number | size * 0.4 | Font size in pixels (auto-calculated if not provided) | | fontWeight | number \| string | 600 | Font weight (100-900 or CSS keywords) | | lineHeight | number \| string | size + "px" | Line height for vertical centering | | letterSpacing | number \| string | 0 | Letter spacing in pixels or CSS units |

InitialOptions

Control how initials are extracted from names:

| Property | Type | Default | Description | |----------|------|---------|-------------| | maxLength | number | Infinity | Maximum number of initials to display | | uppercase | boolean | true | Convert initials to uppercase | | fallback | string | "" | Fallback text when name is empty or invalid |

Examples

Basic Avatar

<InitialsAvatar name="John Doe" />

Custom Size and Colors

<InitialsAvatar 
  name="Jane Smith"
  styles={{
    size: 80,
    bgColor: "#10b981",
    textColor: "#ffffff"
  }}
/>

Square Avatar with Rounded Corners

<InitialsAvatar 
  name="Alice Johnson"
  styles={{
    size: 60,
    radius: 8,
    bgColor: "#f59e0b"
  }}
/>

Custom Font Styling

<InitialsAvatar 
  name="Bob Wilson"
  styles={{
    size: 100,
    fontFamily: "Arial, sans-serif",
    fontSize: 45,
    fontWeight: 700,
    letterSpacing: 2
  }}
/>

Limit Initials Length

<InitialsAvatar 
  name="Christopher Alexander Montgomery"
  options={{
    maxLength: 2  // Will show "CA" instead of "CAM"
  }}
/>

Lowercase Initials

<InitialsAvatar 
  name="David Brown"
  options={{
    uppercase: false
  }}
/>

With Fallback

<InitialsAvatar 
  name=""
  options={{
    fallback: "?"
  }}
  styles={{
    bgColor: "#6b7280"
  }}
/>

Complete Custom Example

<InitialsAvatar 
  name="Emily Rose Parker"
  styles={{
    size: 120,
    radius: "20%",
    bgColor: "#8b5cf6",
    textColor: "#fef3c7",
    fontFamily: "Georgia, serif",
    fontSize: 50,
    fontWeight: 500,
    letterSpacing: 3
  }}
  options={{
    maxLength: 2,
    uppercase: true
  }}
/>

How Initials Are Extracted

The component intelligently extracts initials from names:

1. Removes special characters like hyphens, periods, and apostrophes
2. Splits the name by spaces
3. Takes the first letter of each word
4. Applies the maxLength limit if specified
5. Converts to uppercase by default (unless uppercase: false)

Examples:

• "John Doe" → "JD"
• "Mary-Jane Watson" → "MJW"
• "Dr. James Smith Jr." → "DJSJ"
• "Anne O'Brien" → "AOB"

TypeScript Support

The package includes full TypeScript definitions with automatic type inference. No manual type definitions needed!

Available Types

The package exports the following types:

• InitialsAvatar - The main component
• StyleProps - Type for styling configuration
• InitialsAvatarProps - Type for component props
• InitialOptions - Type for initials extraction options
• getInitials - Utility function for extracting initials

TypeScript Usage

import { InitialsAvatar } from 'react-intials-avatar-generator';
import type { 
  StyleProps, 
  InitialsAvatarProps, 
  InitialOptions 
} from 'react-intials-avatar-generator';

// Define styles with type safety
const styles: StyleProps = {
  size: 60,
  bgColor: "#3b82f6",
  textColor: "#ffffff",
  radius: "50%"
};

// Define options with type safety
const options: InitialOptions = {
  maxLength: 2,
  uppercase: true,
  fallback: "?"
};

// Use in your component
function MyAvatar() {
  return (
    <InitialsAvatar 
      name="John Doe"
      styles={styles}
      options={options}
    />
  );
}

Type Definitions

All types are automatically included when you install the package. TypeScript will provide:

• ✅ Full autocomplete for all props
• ✅ Type checking for prop values
• ✅ IntelliSense documentation
• ✅ Error detection at compile time

No need to create separate type.d.ts files!

API Reference

Exported Components and Types

// Component
export { InitialsAvatar }

// Types
export type { StyleProps, InitialsAvatarProps, InitialOptions }

// Utility
export { getInitials }

Using the getInitials Utility

You can also use the getInitials function directly:

import { getInitials } from 'react-intials-avatar-generator';

const initials = getInitials("John Doe", { 
  maxLength: 2, 
  uppercase: true 
});
// Returns: "JD"

Browser Support

Works in all modern browsers that support React 18+:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Package Information

• Size: ~1.2KB (gzipped)
• Dependencies: React 18+ (peer dependency)
• TypeScript: Full type definitions included
• Module Formats: ESM and UMD

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Ankit Kumar Pandey

Repository

• GitHub: https://github.com/Ankit91153/react-initials-avatar
• Issues: https://github.com/Ankit91153/react-initials-avatar/issues

Keywords

react, avatar, initials, react-avatar, profile-avatar, user-avatar, placeholder-avatar, avatar-component, typescript, react-component