Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/agneym/react-avatar

👤Create Image Avatars with text based fallbacks.
https://github.com/agneym/react-avatar

component javascript react styled-components typescript

Last synced: about 2 months ago
JSON representation

👤Create Image Avatars with text based fallbacks.

Host: GitHub
URL: https://github.com/agneym/react-avatar
Owner: agneym
License: mit
Created: 2020-03-12T06:59:47.000Z (almost 5 years ago)
Default Branch: master
Last Pushed: 2024-09-12T02:41:51.000Z (3 months ago)
Last Synced: 2024-10-31T09:27:45.271Z (about 2 months ago)
Topics: component, javascript, react, styled-components, typescript
Language: TypeScript
Homepage: https://agneym.github.io/react-avatar/?path=/docs/
Size: 4.25 MB
Stars: 10
Watchers: 3
Forks: 2
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # React Avatar



  

    

  

  

    

  

  

    

  

  

    

  

  

    

  



[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)

Create Image Avatars with text based fallbacks. 

[Demo Storybook](https://agneym.github.io/react-avatar/?path=/docs/)

# Features ✨

1. Ability to render image avatar or text avatar as circle or square.

1. Ability to render text based fallbacks for images for the time they take to load or error.

1. Renders text based avatars and backgrounds based on text passed in.

1. Autoscales text if it doesn't fit the container width.

1. Automatically determines readable text color depending on background.

1. Exposes a hook to use/generate gravatar for a user.

1. Exposes a context so you can configure avatar components across your application.

## Install

```sh

npm install @agney/react-avatar

# OR

yarn add @agney/react-avatar

```

Requires React v16.8 or above and Styled Components v4 or above.

## Usage

```javascript

import React from "react";

import { Avatar } from "@agney/react-avatar";

const App = () => {

  return (

    

  );

}

export default App;

```

## API

|  	| Description 	| Default Value 	|

|:-------------:	|----------------------------------------------------------------------------------------------------------------------------------------------------------------------	|-----------------------------------------------------------------------------------	|

| src 	| Source of image to be displayed 	|  	|

| text 	| Text to be displayed as fallback 	|  	|

| imageAlt 	| Alt tag for image  	| '' - decorative 	|

| shape 	| shape of avatar. options: 'circle' | 'square' 	| circle 	|

| htmlWidth 	| width of image element and text fallback. 	| 100% 	|

| htmlHeight 	| height of image element and text fallback 	| same as `htmlWidth` 	|

| backgrounds 	| Array of background colors  	| ['#3c40c6','#ffa801','#485460','#0be881','#f53b57'] 	|

| bgColor 	| background color for specific text fallback. 	| picks random from `backgrounds`, this changes according to `text` prop passed in. 	|

| textColor 	| text color for specific text fallback 	| readable dark or light color depending on background. 	|

| textProcessor 	| function to process visible text inside the avatar. Original text will be used for hashing so even ones with same initials inside avatar can have different backgrounds. 	| (text) => text 	|

| className 	| className on the wrapper. can be used for wrapping with CSS-in-JS frameworks 	|  	|

See [Storybook](https://agneym.github.io/react-avatar/?path=/docs) for more examples and code snippets.

### Context 

Package exposes a context in the form of `AvatarContext`. 

```javascript

import { Avatar, AvatarContext } from '../.';

function App() {

  const contextValue = React.useMemo(() => ({

    backgrounds: ['#000000', '#DD2C00', '#6200EA', '#3F51B5'], // Any props used by Avatar can be used here.

  }), []);

  return (

    

      


        

        

      

    

  )

}

```

Values on the Context Provider are overridden by any props that are on the individual component. Context Provider is not compulsory for usage of Avatar component. Read more about [Context API on docs](https://reactjs.org/docs/context.html).

### `useGravatar` hook

Gravatars or Globally Recognized Avatars is a free service that allows you to share profile pictures/avatars across different sites and services. `react-avatar` exposes a hook that makes it easier for you to request and use these gravatars in your application.

#### Usage:

```javascript

import React from "react";

import { Avatar, useGravatar } from "@agney/react-avatar";

const App = () => {

  const url = useGravatar('[email protected]');

  return (

    

  );

}

export default App;

```

#### API

| Argument 	| Description 	| Default 	|

|---------------------	|------------------------------------------------------------------------------------------------------------------------------------------------------------------------	|---------	|

| email 	| Email of the person for which gravatar is to be fetched 	|  	|

| config 	| configuration object. following fields are part of this object 	|  	|

| config.size 	| number representing height & width of image. 1px up to 2048px 	| 80 	|

| config.defaultImage 	| If the image is not available, gravatar defaults to this property. You can provide a custom URL image to default to or one of the alternatives that Gravatar supports. 	|  	|

| config.forceDefault 	| Always returns the default image if true 	| false 	|

| config.rating 	| Gravatar allows users to self rate their images. If required pass in a higher rating.  	| g 	|

For a complete list of available options, view [Gravatar docs](https://en.gravatar.com/site/implement/images/)

## 🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/agneym/react-avatar/issues).

### Development

We use [`yarn` v1](https://classic.yarnpkg.com/) for development. 

```sh

yarn

yarn start

# To run example

cd example

yarn start

# Running storybook

yarn run storybook

```

### Run tests

```sh

yarn test

```

## Show your support

Give a ⭐️ if this project helped you!



  



## 📝 License

Copyright © 2020 [Agney Menon ](https://github.com/agneym).


This project is [MIT](https://github.com/agneym/react-avatar/blob/master/LICENSE) licensed.

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    
_{Agney Menon}
📖 💻 🤔

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!