@lueur/avatar
v0.1.8
Published
A TypeScript package to generate customizable SVG user avatars.
Downloads
30
Maintainers
oseelazaroReadme
@lueur/avatar
A lightweight and customizable TypeScript package for generating beautiful SVG user avatars based on usernames or custom text.
Table of Contents
Key Features
🎨 Generate SVG Avatars: Outputs a complete SVG string you can use directly in HTML or as a data URI.
👤 Username-Based Initials: Automatically extracts initials from a given username (e.g., "John Doe" becomes "JD").
🎯 Deterministic Colors: Generates consistent, aesthetically pleasing background colors for each unique username.
🔄 Automatic Text Contrast: Ensures initials are always readable by choosing an appropriate black or white text color.
⚙️ Highly Customizable:
- Set width and height.
- Choose square or circle shapes.
- Override background and text colors.
- Control initials length, font family, and font size.
- Provide custom text instead of initials.
- Add arbitrary SVG attributes to the root element.
📦 TypeScript Support: Fully typed for a great developer experience in TypeScript projects.
Installation
You can install the package using npm or yarn:
npm install @lueur/avatar
# or
yarn add @lueur/avatarUsage
Basic Usage
Import generateAvatarSvg and pass a username. By default, it creates a 100x100 square avatar with two initials and a deterministically generated background color.
import { generateAvatarSvg } from '@lueur/avatar';
// Generate a basic avatar SVG string for "John Doe"
const johnDoeAvatar = generateAvatarSvg('John Doe');
console.log(johnDoeAvatar);Customizing Avatars
The generateAvatarSvg function accepts an optional options object for extensive customization.
import { generateAvatarSvg } from '@lueur/avatar';
// Custom size and specific colors
const customColorsAvatar = generateAvatarSvg('Sarah Connor', {
width: 80,
height: 80,
backgroundColor: '#3498db', // A nice blue
textColor: '#ffffff', // White text
});
// Circular avatar with a single initial and custom font
const circularAvatar = generateAvatarSvg('Michael B Jordan', {
width: 60,
height: 60,
shape: 'circle',
initialsLength: 1, // Only show "M"
fontFamily: 'Verdana, sans-serif',
fontSize: 30,
});
// Avatar with custom text and additional SVG attributes
const specialAvatar = generateAvatarSvg('Guest User', {
width: 120,
height: 120,
backgroundColor: '#FF6600',
textColor: '#000000',
text: 'GU',
svgAttributes: {
'data-user-id': 'guest-123',
'class': 'avatar-icon',
'title': 'Guest Avatar'
}
});Using Avatars in HTML
You can directly embed the generated SVG string into your HTML:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Avatar Examples</title>
<style>
body { font-family: sans-serif; display: flex; flex-wrap: wrap; gap: 20px; padding: 20px; }
.avatar-container { text-align: center; }
.avatar-container p { margin-top: 5px; font-size: 0.9em; color: #555; }
.my-custom-class { border: 2px solid purple; border-radius: 8px; }
</style>
</head>
<body>
<div class="avatar-container">
<div id="johnDoeAvatar"></div>
<p>John Doe</p>
</div>
<div class="avatar-container">
<div id="aliceCircular"></div>
<p>Alice (Circular)</p>
</div>
<div class="avatar-container">
<div id="customAttrAvatar"></div>
<p>Custom Attrs</p>
</div>
<script type="module">
import { generateAvatarSvg } from '@lueur/avatar';
document.getElementById('johnDoeAvatar').innerHTML = generateAvatarSvg('John Doe');
document.getElementById('aliceCircular').innerHTML = generateAvatarSvg('Alice', { shape: 'circle', width: 60, height: 60 });
document.getElementById('customAttrAvatar').innerHTML = generateAvatarSvg('Bob Smith', {
width: 70, height: 70, initialsLength: 2,
svgAttributes: { class: 'my-custom-class' }
});
</script>
</body>
</html>You can also use the SVG string as a data URI in an <img> tag:
const dataUri = generateAvatarDataUri('Emma Watson', { width: 50, height: 50 });
// In JSX
// <img src={dataUri} alt="Emma Watson Avatar" />API Reference
generateAvatarSvg(username: string, options?: AvatarOptions): string
The main function to create an SVG avatar.
username(string, required): The name of the user. Initials will be derived from this unlessoptions.textis provided.options(AvatarOptions, optional): An object to customize the avatar's appearance.- Returns: A string containing the complete SVG markup.
generateAvatarDataUri(username: string, options?: AvatarOptions): string
This function uses generateAvatarSvg function (above) to generate an svg string.
It then generates a base64 string that can be used as an image data uri to display the avatar as an actual image.
username(string, required): The name of the user. Initials will be derived from this unlessoptions.textis provided.options(AvatarOptions, optional): An object to customize the avatar's appearance.- Returns: A string containing the base64 value of the SVG image.
AvatarOptions Interface
interface AvatarOptions {
width?: number;
height?: number;
backgroundColor?: string;
textColor?: string;
shape?: AvatarShape;
initialsLength?: number;
fontFamily?: string;
fontSize?: number;
text?: string;
svgAttributes?: { [key: string]: string };
}AvatarShape Type
type AvatarShape = 'square' | 'circle';How It Works
- Initials Extraction: Cleans and processes the username to extract initials. (e.g., "Dr. John Paul Smith Jr." → "JPS").
- Color Generation: A hash from the username deterministically maps to a background color.
- Text Contrast: Based on background luminance, text color is chosen as black or white for readability.
- SVG Assembly: Combines options into a valid SVG string using the calculated styles and text.
Contributing
Contributions are welcome!
- Fork the repository.
- Create a new branch:
git checkout -b feature/your-feature-name - Make your changes.
- Write tests.
- Commit:
git commit -m 'feat: Add feature' - Push:
git push origin feature/your-feature-name - Open a pull request.
💖 Support This Project
If you find this project helpful, consider sponsoring:
License
This project is licensed under the MIT License. See the LICENSE file for details.