Open Peeps Style Overview
Relevant source files
The following files were used as context for generating this wiki page:- packages/avatar/src/open-peeps/index.ts
- packages/avatar/src/open-peeps/schema.ts
- packages/avatar/src/open-peeps/types.ts
- packages/avatar/src/index.ts
- packages/avatar/src/config/gender.ts
- packages/avatar/src/open-peeps/components/face.ts
- packages/avatar/src/open-peeps/components/facialHair.ts
- README.md
The Open Peeps style is a feature within the @nextorders/avatar package for generating highly customizable SVG avatars. It is based on the "Open Peeps" design library by Pablo Stanley, which is licensed under CC0 1.0. This system uses a component-based architecture to assemble various parts of an avatar, such as head, face, and accessories, based on a set of provided options.
The core of this style is the create function, which orchestrates the selection of components and colors to build the final SVG string. It leverages a pseudo-random number generator (PRNG) seeded by a user-provided string to ensure deterministic avatar generation. The style is highly configurable through the OpenPeepsOptions interface, allowing for fine-grained control over the final appearance.
Sources: packages/avatar/src/open-peeps/index.ts:1-15, README.md:5-7
Core Generation Process
The avatar generation process for the Open Peeps style is initiated by the create function. This function takes a PRNG instance and user options, retrieves the necessary components and colors, and assembles them into an SVG structure.
The following diagram illustrates the data flow within the create function.
This diagram shows how the create function uses helper utilities to gather avatar parts and colors, then combines them into a final SVG body.
Sources: packages/avatar/src/open-peeps/index.ts:16-29
SVG Structure
The final SVG is constructed by layering several <g> (group) elements, each containing a specific part of the avatar. Each group is positioned using a transform attribute.
- Base Body: A base path for the torso and shoulders, filled with the selected skin and clothing colors.
- Head: The head/hair component.
- Face: The facial expression component.
- Facial Hair: The facial hair component, if applicable.
- Accessories: The accessories component (e.g., glasses), if applicable.
// packages/avatar/src/open-peeps/index.ts:20-24
body: `<g fill-rule="evenodd" clip-rule="evenodd">...</g>
<g transform="matrix(.99789 0 0 1 156 62)">${components.head?.value(colors) ?? ''}</g>
<g transform="translate(315 248)">${components.face?.value(colors) ?? ''}</g>
<g transform="translate(279 400)">${components.facialHair?.value(colors) ?? ''}</g>
<g transform="translate(203 303)">${components.accessories?.value(colors) ?? ''}</g>`,
Sources: packages/avatar/src/open-peeps/index.ts:20-24
Configuration Options
The appearance of an Open Peeps avatar is controlled by the OpenPeepsOptions interface. These options allow specifying which components to use, their probability of appearing, and what colors to apply.
This diagram shows the structure of the OpenPeepsOptions object.
Sources: packages/avatar/src/open-peeps/types.ts:1-10
The available options are formally defined in a JSON schema, which includes default values and constraints.
| Property | Type | Description | Default Value |
|---|---|---|---|
accessories | string[] | An array of possible accessory styles. | ['eyepatch', 'glasses', ...] |
accessoriesProbability | integer | The probability (0-100) of an accessory appearing. | 20 |
clothingColor | string[] | An array of possible clothing colors (hex codes). | ['e78276', 'ffcf77', ...] |
face | string[] | An array of possible facial expressions. | ['angryWithFang', 'awe', ...] |
facialHair | string[] | An array of possible facial hair styles. | ['chin', 'full', ...] |
facialHairProbability | integer | The probability (0-100) of facial hair appearing. | 10 |
head | string[] | An array of possible head/hair styles. | ['afro', 'bangs', ...] |
skinColor | string[] | An array of possible skin colors (hex codes). | ['ffdbb4', 'edb98a', ...] |
Sources: packages/avatar/src/open-peeps/schema.ts:4-178
Component System
The avatar is built from a collection of components, each representing a distinct visual part. The main component groups are head, face, facialHair, and accessories.
Sources: packages/avatar/src/open-peeps/types.ts:74-75
Each component is a function that accepts a ColorPickCollection (a record of color names to hex values) and returns an SVG path string.
// Example from packages/avatar/src/open-peeps/components/face.ts:4
export const face: ComponentGroup = {
angryWithFang: () =>
`<path fill-rule="evenodd" clip-rule="evenodd" d="..." fill="#000"/>`,
awe: () =>
`<g fill-rule="evenodd" clip-rule="evenodd">...</g>`,
// ... and so on for all face emotions
}
Sources: packages/avatar/src/open-peeps/components/face.ts:3-5, packages/avatar/src/open-peeps/types.ts:71-73
Component Types
The available component names for each category are defined as string literal types.
| Type | Description | Example Values |
|---|---|---|
Head | Defines hairstyle or headwear. | afro, bun, hatHip, longCurly, shaved1 |
FaceEmotion | Defines the facial expression. | smile, calm, cheeky, rage, tired |
FacialHair | Defines the style of facial hair. | chin, full, goatee1, moustache1 |
Accessories | Defines accessories like glasses. | eyepatch, glasses, sunglasses |
Sources: packages/avatar/src/open-peeps/types.ts:12-70
Gender-Specific Customization
The Open Peeps style supports gender-specific configurations that alter the available components and probabilities. The MALE_CONFIG and FEMALE_CONFIG objects define these differences, primarily affecting the head options and facialHairProbability.
| Configuration | head Styles | facialHairProbability |
|---|---|---|
| Male | afro, dreads1, hatHip, flatTop, mohawk, pomp, short1, etc. | 10 |
| Female | afro, dreads1, hatHip, bangs, bun, cornrows, long, medium1, etc. | 0 |
This allows for generating avatars that are more aligned with a specified gender by default.
Sources: packages/avatar/src/config/gender.ts:3-36
Integration and Usage
The Open Peeps style is integrated into the main createAvatar function. This function validates user options, builds a complete options object, and then passes it to the core avatar creation logic.
The following sequence diagram shows how a call to createAvatar flows through the system to generate an Open Peeps avatar.
This diagram illustrates the call chain, starting from the public createAvatar function down to the style-specific create function.
Sources: packages/avatar/src/index.ts:13-21, packages/avatar/src/core/index.ts:10-13
Summary
The Open Peeps style module is a robust and flexible system for generating SVG avatars. Its component-based architecture, extensive configuration options, and clear separation of concerns make it a powerful part of the @nextorders/avatar library. By leveraging a JSON schema for validation and providing gender-specific defaults, it offers a developer-friendly API for creating a wide variety of personalized avatars.