DOCSEARCHbyAlgolia
Submit Docs

avataaars React Component

repository·master·Indexed 21 days ago

https://github.com/fangpenlin/avataaars

A React component library for rendering Avataaars, an SVG-based avatar system. Version 2.0.0 allows developers to render complete avatars using the Avatar component or individual pieces (such as eyes, hair, or clothing) using the Piece component. It includes highly customizable options for skin tones, clothing colors, facial features, and decorative clothing graphics.

Tokens
7.4K
Snippets
29
Records
42
Agent score
70%

What's inside avataaars

  1. Build a custom editor using OptionContext

    master
    For advanced use cases like building a custom avatar editor, you can combine the lower-level Avatar component with OptionContext. OptionContext is used to collect and manage the available options for the avatar pieces. For implementation details, refer to the source code of the avataaars-generator.

  3. Manage avatar options with OptionContext

    master

    The OptionContext class serves as the central state manager for avatar customization. It tracks available options (like hair styles, eye shapes, etc.), their current availability, and the selected values for each option key. It allows developers to subscribe to changes in both the overall state and specific value updates.

    Key capabilities include:

    • State Management: Tracks OptionState for each customization key.
    • Value Tracking: Maintains the current selection for each option via setData or setValue.
    • Event Subscription: Listen for state changes or specific value changes using listener methods.
    • Dynamic Updates: Update available options or default values at runtime.

  4. Use the Avatar component

    master

    Import the Avatar component to render a complete Avataar SVG. You can customize the appearance by passing props such as topType, accessoriesType, hairColor, clotheType, eyeType, and more. You can also control the container shape using the avatarStyle prop (e.g., 'Circle').

    import * as React from 'react'
import Avatar from 'avataaars'

export default class MyComponent extends React.Component {
  render () {
    return 
      <div>
        Your avatar:
        <Avatar
          style={{width: '100px', height: '100px'}}
          avatarStyle='Circle'
          topType='LongHairMiaWallace'
          accessoriesType='Prescription02'
          hairColor='BrownDark'
          facialHairType='Blank'
          clotheType='Hoodie'
          clotheColor='PastelBlue'
          eyeType='Happy'
          eyebrowType='Default'
          mouthType='Smile'
          skinColor='Light'
        />
      </div>
  </div>
}

  5. Render individual avatar pieces with the Piece component

    master

    If you need to showcase or manipulate specific parts of the avatar independently, use the Piece component. The pieceType prop determines which part to render (e.g., 'mouth', 'eyes', 'eyebrows', 'accessories', 'top', 'facialHair', 'clothe', 'graphics', or 'skin'). Use the corresponding type prop (like mouthType, eyeType, etc.) to select the specific style.

    import * as React from 'react'
import {Piece} from 'avataaars';

export default class MyComponent extends React.Component {
  render () {
    return 
      <div>
        <Piece pieceType="mouth" pieceSize="100" mouthType="Eating"/>
        <Piece pieceType="eyes" pieceSize="100" eyeType="Dizzy"/>
        <Piece pieceType="eyebrows" pieceSize="100" eyebrowType="RaisedExcited"/>
        <Piece pieceType="accessories" pieceSize="100" accessoriesType="Round"/>
        <Piece pieceType="top" pieceSize="100" topType="LongHairFro" hairColor="Red"/>
        <Piece pieceType="facialHair" pieceSize="100" facialHairType="BeardMajestic"/>
        <Piece pieceType="clothe" pieceSize="100" clotheType="Hoodie" clotheColor="Red"/>
        <Piece pieceType="graphics" pieceSize="100" graphicType="Skull" />
        <Piece pieceType="skin" pieceSize="100" skinColor="Brown" />
      </div>
    </div>
  }
}

  6. Use the Graphics component to add decorations to clothing

    master

    The Graphics component is the primary entry point for adding decorative patterns or icons to an avatar's clothing. It accepts a maskID prop, which is used to ensure the graphic is correctly clipped to the shape of the clothing item via an SVG mask.

    To use it, import the Graphics component and pass the maskID provided by your clothing component's context or props.

    import Graphics from 'avataaars/src/avatar/clothes/Graphics';

// Inside a clothing component render method:
<Graphics maskID={this.props.maskID} />

// To select a specific graphic (e.g., 'Pizza'):
<Graphics option='Pizza' maskID={this.props.maskID} />

  7. Use the Eyebrow component

    master

    The Eyebrow component is a React component used to render various eyebrow styles for an Avataaars avatar. It uses a Selector pattern to manage eyebrow options. When used, it will render the eyebrow style corresponding to the current EyebrowOption provided via props.

    import Eyebrow from 'avataaars/src/avatar/face/eyebrow';

// Usage within a component
<Eyebrow option={someEyebrowOption} />

  8. Use the Top component to manage head and hair options

    master

    The Top component is a container used to manage the 'top' layer of an Avataaars avatar (hair, hats, hijabs, etc.). It uses a Selector pattern to allow users to switch between different visual styles. By wrapping other avatar components as children, Top acts as a controller that renders the specific sub-component corresponding to the selected option.

    It defaults to LongHairStraight if no option is provided.

    import Top from 'avataaars/src/avatar/top';

// Usage within an avatar composition
<Top>
  {/* The children passed here will be rendered by the selected sub-component */}
</Top>

  9. Use Clothing Graphic components

    master

    Clothing graphics like Skull, Bat, or Diamond are React components used to render decorations on an avatar's clothing. They require a maskID prop, which is a string used to create an SVG mask so the graphic stays within the bounds of the clothing item.

    Each component has a static optionValue property used by the library's selection logic to identify the chosen graphic.

    // Example usage of a graphic component
<Skull maskID="some-unique-mask-id" />

  10. Use OptionContext methods to manage state and values

    master

    The OptionContext class provides several methods to manipulate the avatar configuration state:

    State and Option Management

    • setDefaultValue(key: string, defaultValue: string): Sets the fallback value for a specific option key.
    • setOptions(key: string, options: Array<string>): Updates the list of available string options for a specific key.
    • getOptionState(key: string): Returns the OptionState for a key, or null if not found.
    • getValue(key: string): Returns the current selected value for a key. It returns the value from the internal data store, or falls back to the defaultValue if one is set.

    Data Synchronization

    • setData(data: { [index: string]: string }): Sets the entire configuration object (the single source of truth) and notifies listeners.
    • setValue(key: string, value: string): Updates a specific key's value and triggers value change listeners.

    Event Listeners

    • addStateChangeListener(listener: () => void): Registers a callback to be executed whenever the internal state changes.
    • addValueChangeListener(listener: (key: string, value: string) => void): Registers a callback that receives the key and the new value whenever a value is updated.

  11. Use the Accessories component

    master

    The Accessories component is a React component used to render various head accessories for an Avataaars avatar. It uses a Selector component internally to manage the selection of different accessory styles from the available AccessoriesOption set.

    Available accessory styles included in this component are:

    • Blank (no accessory)
    • Kurt
    • Prescription01
    • Prescription02
    • Round
    • Sunglasses
    • Wayfarers
    import Accessories from 'avataaars/src/avatar/top/accessories';

  12. Use the Mouth component to customize avatar expressions

    master

    The Mouth component is a React component used to render different mouth styles for an Avataaars avatar. It uses a Selector pattern to manage the active mouth option based on the MouthOption provided via props.

    Available mouth styles included in the component are:

    • Concerned
    • Default
    • Disbelief
    • Eating
    • Grimace
    • Sad
    • ScreamOpen
    • Serious
    • Smile
    • Tongue
    • Twinkle
    • Vomit
    import Mouth from 'avataaars/src/avatar/face/mouth';

// Usage within an avatar composition
<Mouth option={MouthOption.Smile} />