repository·main·Indexed 23 days ago
https://github.com/dapi-labs/react-nice-avatarA React component library for generating customizable, stylized avatar illustrations. It features the Avatar component and a genConfig function that supports seed-based deterministic generation, manual customization, or random configuration. Users can control attributes such as face color, hair style, clothing, and container shapes (circle, rounded, or square).
To use the avatar component, import Avatar and genConfig. You can generate a configuration object using genConfig and then spread that configuration into the Avatar component.
genConfig supports three modes:
You can install the package using npm or yarn.
npm install react-nice-avataryarn add react-nice-avatarTo ensure a specific user or entity always gets the same avatar without storing the entire configuration object, pass a unique string to genConfig().
The function converts the string into a hash code and uses it to pick attributes (sex, face color, hair style, etc.) from the available options. This results in a consistent, repeatable avatar for any given input string.
genConfig function is used to create a configuration object that defines the appearance of the avatar. It can be used to ensure deterministic avatars based on a seed, or to create randomized/customized ones.Options can be passed directly to the Avatar component as React props or provided to the genConfig function.
Note on React Props: The following keys are exclusive to React props and cannot be used inside genConfig: id, className, style, and shape.
| key | type | default | accept | tips |
| -------------- | ------ | ------- | ---------------------------------------- | -------------------- |
| `id` | string | | | Only for React Props |
| `className` | string | | | Only for React Props |
| `style` | object | | | Only for React Props |
| `shape` | string | circle | circle, rounded, square | Only for React Props |
| `sex` | string | | man, woman | |
| `faceColor` | string | | | |
| `earSize` | string | | small, big | |
| `hairColor` | string | | | |
| `hairStyle` | string | | normal, thick, mohawk, womanLong, womanShort | |
| `hairColorRandom` | boolean | false | | thick,mohawk default only be black |
| `hatColor` | string | | | |
| `hatStyle` | string | | none, beanie, turban | Usually is none |
| `eyeStyle` | string | | circle, oval, smile | |
| `glassesStyle` | string | | none, round, square | Usually is none |
| `noseStyle` | string | | short, long, round | |
| `mouthStyle` | string | | laugh, smile, peace | |
| `shirtStyle` | string | | hoody, short, polo | |
| `shirtColor` | string | | | |
| `bgColor` | string | | | |
| `isGradient` | boolean | false | | |The NiceAvatar component accepts a configuration object via its props to customize the avatar's appearance. You can specify features like sex, hairStyle, eyeStyle, and colors for various elements.
Available configuration options include:
sex: 'man' | 'woman'earSize: 'small' | 'big'hairStyle: 'normal' | 'thick' | 'mohawk' | 'womanLong' | 'womanShort'hatStyle: 'beanie' | 'turban' | 'none'eyeStyle: 'circle' | 'oval' | 'smile'glassesStyle: 'round' | 'square' | 'none'noseStyle: 'short' | 'long' | 'round'mouthStyle: 'laugh' | 'smile' | 'peace'shirtStyle: 'hoody' | 'short' | 'polo'eyeBrowStyle: 'up' | 'upWoman'faceColor, hairColor, hatColor, shirtColor, bgColor (strings)hairColorRandom: booleanisGradient: booleanshape: 'circle' | 'rounded' | 'square'The genConfig function is used to generate a complete configuration object for an avatar. It supports two modes of operation:
defaultOptions list. If a property is provided in the object, it will be used instead of a random one.string instead of an object. The function will use the string as a seed to deterministically generate a configuration using a hash code. This allows you to generate the same avatar every time you use the same string.Note that genConfig includes internal logic to ensure visual harmony, such as avoiding certain hair colors that clash with face colors or ensuring shirt colors don't match hair/hat colors.
genConfig function can be used to generate a complete, randomized AvatarFullConfig object. This is useful for creating diverse avatars without manually specifying every property. You can pass an existing configuration or a string to influence the generation, but it returns a Required<AvatarFullConfig> object containing all possible avatar properties.The ReactNiceAvatar component accepts the following props to customize the avatar's appearance:
| Prop | Type | Description |
|---|---|---|
id | string | HTML ID for the container div |
className | string | CSS class for the container div |
style | object | Inline styles for the container div |
shape | "circle" | "rounded" | "square" | The shape of the avatar container (default: "circle") |
sex | string | The sex of the avatar (uses defaultOptions.sex) |
faceColor | string | Color of the face |
earSize | string | Size of the ears (uses defaultOptions.earSize) |
hairColor | string | Color of the hair |
hairStyle | string | Style of the hair (uses defaultOptions.hairStyleMan or defaultOptions.hairStyleWoman) |
hairColorRandom | boolean | If true, hair color is randomized (default: false) |
hatColor | string | Color of the hat |
hatStyle | string | Style of the hat (uses defaultOptions.hatStyle) |
eyeStyle | string | Style of the eyes (uses defaultOptions.eyeStyle) |
glassesStyle | string | Style of the glasses (uses defaultOptions.glassesStyle) |
noseStyle | string | Style of the nose (uses defaultOptions.noseStyle) |
mouthStyle | string | Style of the mouth (uses defaultOptions.mouthStyle) |
shirtStyle | string | Style of the shirt (uses defaultOptions.shirtStyle) |
shirtColor | string | Color of the shirt |
bgColor | string | Background color of the container |
isGradient | boolean | Whether to use a gradient (internal logic) |
The NiceAvatarProps include a shape property that determines the container geometry of the avatar. Supported values are:
'circle''rounded''square'The ReactNiceAvatar component is the primary entry point for generating customizable avatars. It accepts a variety of props to control the appearance of the face, hair, clothing, and background.
Supported shape options for the container are:
circle (default)rounded (6px border radius)square (0 border radius)You can also enable hairColorRandom to randomize the hair color independently of the hairColor prop.