Generate Stunning Gradient Avatars with Ease

Hey everyone, Simplr here!

We’re back with another open-source project that we’re incredibly excited to share with you all. This time, it’s all about visual identity and user representation: @simplr-sh/avatar. If you’re looking for a simple and elegant way to generate beautiful, gradient-based avatars for your web applications, you’ve come to the right place.

In the world of web development, visual consistency and personalized user experiences are paramount. And a key component of that is the user avatar. But let’s be honest, handling avatar generation can sometimes be tedious. You need to think about placeholders, styling, and potentially complex backend logic. That’s why we set out to create @simplr-sh/avatar, a TypeScript library that makes the process seamless and delightful.

Why We Created @simplr-sh/avatar

The inspiration for this project came from the desire to have a simple, yet elegant, way of generating avatars without the need for image uploads or complex APIs. We wanted something that was performant, customizable, and just looked good. The incredible work by the Vercel team in their avatar component was a big influence, and we wanted to offer a similar solution, but focused specifically on gradient-based avatars with text overlays.

Image description

What Makes @simplr-sh/avatar Stand Out?

@simplr-sh/avatar is a unique library designed to help you quickly generate awesome gradient-based avatars. Let’s break down the key features:

Gradient-Based Avatars: The core feature of this library. @simplr-sh/avatar generates unique gradient backgrounds for each avatar based on the provided name. This means no two avatars will look exactly the same, adding a touch of personality to your app.
Customizable Text Overlays: Display the user’s initials or any other text of your choice over the gradient background. This gives you even more flexibility in how you want to represent your users.
Easy Customization: You can tailor the appearance of your avatars through simple options such as size and rounded (border radius).
TypeScript Support: The entire library is written in TypeScript, giving you type safety, and a smooth development experience.
Base64 SVG Data URI: The library returns the generated avatar as a Base64 SVG data URI. This is great because you don’t need to worry about storing images on a server or dealing with extra network requests. The avatar is ready to be displayed directly in an HTML img tag.

API Deep Dive: getAvatar(options)

The heart of @simplr-sh/avatar is the getAvatar(options) function. This function is responsible for generating the avatar, and it is incredibly easy to use. Here’s a quick look at the options it accepts:

name (string): The user’s name that is used to generate the gradient background.
text (string): The text to overlay on top of the gradient (e.g., initials).
size (number, optional): The size of the avatar in pixels. The default is 128.
rounded (number, optional): The border radius of the avatar, allowing you to create circular, rounded, or square avatars. The default is 0.

The function returns a Promise that resolves to a string which is the Base64 SVG data URI of the generated avatar.

How to Use @simplr-sh/avatar

Let’s walk through how to use @simplr-sh/avatar in both vanilla JavaScript and React environments:

Vanilla JavaScript Example

import { getAvatar } from '@simplr-sh/avatar';

(async () => {
  // Generate a simple avatar
  const avatar = await getAvatar({
    name: 'John Doe',
    text: 'JD',
    size: 128,
    rounded: 16,
  });

  // Use in HTML
  const img = document.createElement('img');
  img.src = avatar;
  document.body.appendChild(img);
})();

React Example

import { useEffect, useState } from 'react';
import { getAvatar } from '@simplr-sh/avatar';

function Avatar({ name, text, size = 128, rounded = 16 }) {
  const [avatarSrc, setAvatarSrc] = useState<string>('');

  useEffect(() => {
    getAvatar({ name, text, size, rounded })
      .then(setAvatarSrc)
      .catch(console.error);
  }, [name, text, size, rounded]);

  return <img src={avatarSrc} alt={`Avatar for ${name}`} />;
}

// Usage
function App() {
  return <Avatar name="John Doe" text="JD" />;
}

Attribution and Open Source

This package is inspired by, and has code adapted from the amazing work in Vercel’s Avatar repository. We’re incredibly grateful to them for their contributions to the web development community.

This project is fully open-source, and we encourage you to get involved. If you find a bug, have a feature request, or want to contribute to the code, please feel free to check out the repository at: https://github.com/simplr-sh/avatar

Getting Started

Ready to give @simplr-sh/avatar a go? Here’s how to install it:

# Using bun
bun i @simplr-sh/avatar

# Using NPM
npm i @simplr-sh/avatar

# Using Yarn
yarn add @simplr-sh/avatar

Wrapping Up

@simplr-sh/avatar is a simple, yet powerful library that we created to make adding stylish avatars as easy as possible. We poured a lot of effort and love into this project, and we hope it helps you create even more beautiful and engaging web applications.

We’re always open to feedback and suggestions. Let us know in the comments below what you think, or if you have any questions!

#opensource #react #npm #avatars #webdev #ui #javascript #typescript #developers #componentlibrary