Customization Options

Relevant source files

The following files were used as context for generating this wiki page:

• packages/avatar/src/types.ts
• packages/avatar/src/index.ts
• packages/avatar/src/core/types.ts
• packages/avatar/src/core/index.ts
• packages/avatar/src/open-peeps/schema.ts
• packages/avatar/src/config/avatar.ts
• packages/avatar/src/utils/selectors.ts
• packages/avatar/src/core/utils/options.ts
• packages/avatar/src/core/utils/svg.ts
• packages/avatar/src/open-peeps/index.ts

The @nextorders/avatar package provides a robust, layered system for generating and customizing SVG avatars. The primary method of customization is through an options object passed to the main createAvatar function. This system is designed to be both simple for basic use cases and powerful for fine-grained control.

At a high level, users interact with the AvatarOptions type, which provides easy-to-use settings for common attributes like gender, clothing, and emotion. These high-level options are then processed and merged with several layers of configuration, including default SVG settings and style-specific options from the "Open Peeps" collection, to produce the final avatar. This layered approach ensures deterministic, seed-based generation while offering extensive flexibility.

Avatar Generation Flow

The avatar generation process starts with the user-provided AvatarOptions. These options are processed, merged with defaults, and used to assemble the final SVG string.

The following diagram illustrates the high-level sequence of operations when createAvatar is called.

High-Level Customization (AvatarOptions)

The primary interface for customization is the AvatarOptions object. It provides a simple way to control the most common visual aspects of the avatar.

Sources: packages/avatar/src/types.ts:3-9

Option	Type	Description
seed	string	Required. A string used to seed the random number generator, ensuring deterministic output for the same seed.
gender	'male' | 'female'	Determines the set of components available (e.g., hairstyles). If not provided, a gender is chosen randomly.
clothing	'amber' | 'green' | 'blue' | 'teal' | 'pink' | 'violet'	Sets the color of the avatar's clothing. Defaults to a predefined color if not specified.
emotion	1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10	A number from 1 to 10 that maps to a specific facial expression. If not provided, a random face is chosen from all possibilities.

AvatarOptions Processing

The buildOptions function translates the user-friendly AvatarOptions into the more detailed OpenPeepsOptions and Options required by the core generator.

// packages/avatar/src/index.ts:19-29
function buildOptions(data: AvatarOptions): Partial<Options & OpenPeepsOptions> {
  const genderConfig = selectGenderConfig(data.gender)

  return {
    ...SVG_CONFIG,
    ...AVATAR_CONFIG,
    ...genderConfig,
    seed: data.seed,
    face: selectFaceEmotion(data.emotion),
    clothingColor: selectClothingColor(data.clothing),
  }
}

This function:

1. Selects a gender-specific configuration (MALE_CONFIG or FEMALE_CONFIG) which defines available head and facialHair options.
2. Merges default SVG and Avatar configurations (SVG_CONFIG, AVATAR_CONFIG).
3. Maps the numeric emotion to a specific face component name.
4. Maps the clothing color name to a specific hex color value.

Sources: packages/avatar/src/index.ts:19-29, packages/avatar/src/utils/selectors.ts

Core SVG Transformation Options

The core avatar engine provides a set of options for transforming the generated SVG, such as scaling, rotation, and background effects. These are defined in the Options type.

Sources: packages/avatar/src/core/types.ts:18-31

Option	Type	Default (from SVG_CONFIG)	Description
size	number	256	Sets the width and height attributes of the SVG.
scale	number	80	Scales the avatar within the viewbox. 100 is no scaling.
translateX	number	-5	Moves the avatar horizontally as a percentage of the viewbox width.
translateY	number	0	Moves the avatar vertically as a percentage of the viewbox height.
rotate	number	undefined	Rotates the avatar in degrees around its center.
flip	boolean	undefined	Flips the avatar horizontally.
radius	number	undefined	Applies a corner radius to the avatar, creating a clipping mask. Value is a percentage of the viewbox dimension.
clip	boolean	undefined	If true, enables the clipping mask. Used with radius.
backgroundType	BackgroundType[]	['randomGradientLinear']	An array of allowed background types. A type is picked randomly from this array. Options are 'solid', 'gradientLinear', 'randomGradientLinear'.
backgroundColor	string[]	undefined	An array of hex color strings to be used for the background.
backgroundRotation	number[]	undefined	An array of allowed rotation values (in degrees) for gradient backgrounds.

SVG Transformation Pipeline

The core createAvatar function applies these transformations in a specific order to the generated SVG body.

This diagram shows the sequence of SVG transformations applied to the avatar.

*Sources: packages/avatar/src/core/index.ts:29-53, packages/avatar/src/core/utils/svg.ts *

"Open Peeps" Style Options

For advanced customization, you can directly use the options defined by the "Open Peeps" style schema. These options allow for granular control over every component of the avatar. The createAvatar function in index.ts sets some of these based on AvatarOptions, but they can be overridden.

Sources: packages/avatar/src/open-peeps/schema.ts

Option	Type	Default	Description
accessories	string[]	['eyepatch', 'glasses', ...]	Array of allowed accessory components.
accessoriesProbability	integer	20	Probability (0-100) of an accessory being applied.
clothingColor	string[]	['e78276', 'ffcf77', ...]	Array of allowed clothing colors (hex codes).
face	string[]	['angryWithFang', 'awe', ...]	Array of allowed face (emotion) components.
facialHair	string[]	['chin', 'full', ...]	Array of allowed facial hair components.
facialHairProbability	integer	10	Probability (0-100) of facial hair being applied.
head	string[]	['afro', 'bangs', ...]	Array of allowed head (hair/hat) components.
headContrastColor	string[]	['2c1b18', 'e8e1e1', ...]	Array of allowed colors for hair/hat details.
skinColor	string[]	['ffdbb4', 'edb98a', ...]	Array of allowed skin colors.

Option Merging

The system merges options from three sources to create the final configuration used for generation. Options provided by the user have the highest precedence.

This diagram shows how default configurations are combined with user-provided options.

Sources: packages/avatar/src/core/utils/options.ts:25-34

1. Core Schema Defaults: Base defaults for generic SVG options (defined in packages/avatar/src/core/schema.ts, not shown but logic is in options.ts).
2. Style Schema Defaults: Defaults specific to the "Open Peeps" style, such as component lists and probabilities (from packages/avatar/src/open-peeps/schema.ts).
3. User-Provided Options: The options object passed to createAvatar, which has the highest priority and will override any defaults.

This merging is handled by the merge function, which ensures a complete and valid set of options is available for the generator.

Summary

The avatar customization system is built on a layered and merged configuration. The high-level AvatarOptions provide a simple API for common changes, which are translated into more detailed style and core options. For advanced use, developers can directly provide any of the core Options or "Open Peeps" style options to gain fine-grained control over the final SVG output, from individual components to background effects and transformations. This architecture balances ease of use with powerful flexibility.