Options

Everything you can pass to the React component and to createAvatar, with the helpers and types that support them.

`<Avatar>`

@humation/react — a forwardRef component that renders an <svg> element.

PropType

assetsHumationManifest

The asset set to draw with, e.g. humation1 from @humation/assets-humation-1.

TypeHumationManifest

seed?string

Picks a part for every slot deterministically. Explicit selections override the seeded picks.

Typestring

selections?Record<string, string>

Part selections by name, alias, or canonical ID, e.g. { head: 'braids' }.

TypeRecord<string, string>

colors?Record<string, string>

Color slot values. Applied as CSS custom properties on the <svg> element, so a color change never re-renders the content.

TypeRecord<string, string>

background?string | 'transparent'

Background fill. Defaults to the manifest default.

Typestring | 'transparent'

Default'#F6F5F4'

crop?string

Crop id. Humation 1 ships a single crop.

Typestring

Default'avatar'

size?number | string

Rendered size. Numbers keep the crop aspect ratio.

Typenumber | string

title?string

Accessible title. Without it the avatar is treated as decorative.

Typestring

...svgPropsOmit<SVGProps<SVGSVGElement>, 'children'>

Everything else is forwarded to the root <svg>, including className, style, and ref.

TypeOmit<SVGProps<SVGSVGElement>, 'children'>

createAvatar

@humation/core

createAvatar(manifest: HumationManifest, options?: CreateAvatarOptions)

PropType

seed?string

Deterministic picks per slot. Stable per asset package version; adding parts to a slot can change a pick.

Typestring

selections?Record<SelectionSlotId, string>

Canonical part IDs, global aliases, or slot-scoped names. Overrides seeded picks.

TypeRecord<SelectionSlotId, string>

colors?Record<ColorSlotId, HexColor>

Hex values, with or without a leading #.

TypeRecord<ColorSlotId, HexColor>

background?HexColor | 'transparent'

Overrides the manifest default background.

TypeHexColor | 'transparent'

crop?CropId

Overrides the manifest default crop.

TypeCropId

PropType

toString()string

A complete SVG document.

Typestring

toDataUri()string

A data:image/svg+xml URI, ready for an <img src>.

Typestring

toJSON()AvatarJson

The resolved selections, colors, background, and crop, with every part as a canonical ID.

TypeAvatarJson

toRenderData()AvatarRenderData

Composed fragments without the root element, for framework wrappers that build the <svg> themselves.

TypeAvatarRenderData

The returned object exposes four conversions.

Helpers

@humation/core

PropType

resolvePartId(input, manifest, slotId?)string

Resolves a name, alias, or ID to a canonical part ID. Pass slotId to scope a bare name to one slot.

Typestring

getPartsForSlot(manifest, slotId)PartOption[]

Every part in a selection slot (head, body, bottom, item, glasses).

TypePartOption[]

getPartsForUiGroup(manifest, groupId)PartOption[]

Every part in a UI group. Groups are what a picker renders as tabs.

TypePartOption[]

createPartPreview(manifest, part, options?){ toString, toDataUri }

A single-part preview for picker swatches. Options accept colors and background.

Type{ toString, toDataUri }

validateManifest(manifest)ManifestValidationIssue[]

Checks a manifest for structural problems. Useful when authoring a custom asset package.

TypeManifestValidationIssue[]

Manifest types

The manifest is plain data, so you can read it directly instead of hard-coding slot names or color lists.

type HumationManifest = {
  schemaVersion: '1.0';
  template: { id: string; shortId: string; name: string; version: string; license: string };
  defaults: {
    selections: Record<SelectionSlotId, PartOptionId>;
    colors: Record<ColorSlotId, HexColor>;
    background: HexColor | 'transparent';
    crop: CropId;
  };
  colors: ColorSlot[];
  crops: Record<CropId, ViewBox>;
  selectionSlots: SelectionSlot[];
  uiGroups: UiGroup[];
  layerSlots: LayerSlot[];
  parts: PartOption[];
  aliases: AliasEntry[];
};

type PartOption = {
  id: PartOptionId;
  name?: string;
  aliases?: string[];
  selectionSlot: SelectionSlotId;
  uiGroups: UiGroupId[];
  layers: LayerFragment[];
  tags?: string[];
  deprecated?: boolean;
};

type ColorSlot = {
  id: ColorSlotId;
  label: string;
  default: HexColor;
  cssVariable: `--hm-${string}`;
  allowTransparent?: boolean;
};

type AliasEntry = {
  alias: string;
  targetId: PartOptionId;
  status: 'active' | 'deprecated';
  replacementAlias?: string;
};

aliases is what keeps old stored values working. A deprecated entry carries replacementAlias pointing at its successor. See Saving state.