Pricing

Avatar handbook

v2.12.5 · @snowui-design-system/components

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Show user or team avatars as images, text, or gradient fallbacks to make lists, comments, and member information easier to recognize.

When to use it

Use Avatar for one user or team identity and AvatarGroup for overlapping members. Use ordinary lists with Avatar and text for vertical contact details.

  • Use src for the image and fallback / fallbackText for missing images. Pass a stable fallbackSeed for the same identity.

  • Attach a badge with as="badge" or replace the avatar visual with as="avatar-image". Explicit size takes priority, followed by the parent avatar size.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Avatar } from '@snowui-design-system/components';	import { AvatarByewind, SnowLogo } from '@snowui-design-system/resource-svelte';</script> <div style="display: flex; align-items: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">	<Avatar fallbackColor="blue" aria-label="Blue default avatar" size={48} />	<Avatar fallbackColor="cyan" aria-label="Cyan default avatar" size={48} />	<Avatar fallbackColor="green" aria-label="Green default avatar" size={48} />	<Avatar fallbackColor="red" aria-label="Red default avatar" size={48} />	<Avatar fallbackColor="orange" aria-label="Orange default avatar" size={48} />	<Avatar fallbackColor="purple" aria-label="Purple default avatar" size={48} />	<Avatar src={SnowLogo} dataName="SnowUI logo" size={48} />	<Avatar src={AvatarByewind} dataName="ByeWind" size={48} /></div>

API

Keyword Type Default Description
src string | Component — Avatar image URL or icon component
size ResourceSize — The avatar size range is 12/16/20/24/28/32/40/48/80; the explicit value takes precedence, followed by the parent avatar or the general size context, and 16 when there is no context.
fallback Component — Custom avatar component rendered when src is absent or the image fails. By default, Avatar uses a built-in Gradient. For animated avatars, pass GradientMotion; Avatar supplies as="avatar-image", size="100%", radius="inherit", and the resolved stable seed.
fallbackText string — Explicit fallback text when the image is unavailable. Trimmed non-empty text replaces the default Gradient, but an explicit fallback component still takes precedence. Initials are not generated from names automatically.
fallbackColor GradientVariant — Explicit named artistic color for the default Gradient, taking precedence over fallbackSeed and name fallback.
fallbackSeed string | number — Stable identity seed, preferably user.id. A deterministic hash maps it to one of six named colors, so the same seed always gets the same color without storing a color field.
variant AvatarVariant "default" The default style uses a Gradient color selected from a stable identity seed or explicit named color. The empty style uses a gray background and default user icon.
gradientMotion boolean false Whether the default Gradient fallback continuously runs its four-layer base vector deformation. With false, hover still runs ripple deformation and multicolor overlay on demand.
children Snippet — Attached avatar content: as="badge" identifies a badge; as="avatar-image" supplies external avatar art that replaces the default fallback layer.
badgePosition "top" | "bottom" "top" Position as="badge" children at the avatar’s upper or lower right; dot badges also participate in avatar cutout.

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Layout model

Main layout model: intrinsic atomic layout.

  • Avatar exposes one box sized by size, parent size context, or renderHints. It hugs its size as a child of Button, MenuItem, Field, or another external layout.

  • As an inline-level atomic box, Avatar aligns on the midline; an image, Gradient, or empty icon must not shift avatars vertically within a row.

  • The image, default Gradient or empty-icon layer, hover filter, and badge cutout mask are private Avatar layout. No Leading / Content / Trailing slots are exposed.

  • as="badge" identifies an attached badge inside Avatar. Avatar does not emit data-auto-layout or manage general child arrangement.

  • Use AvatarGroup to arrange multiple avatars instead of turning Avatar into a collection layout.

Keywords

Keyword Type Default Description
as string — Declare Avatar’s role in an external host, for example "item" in AvatarGroup. Internal child roles "badge" and "avatar-image" belong to the children protocol.
as string — Declare Avatar’s role in an external host, for example "item" in AvatarGroup. Internal child roles "badge" and "avatar-image" belong to the children protocol.

Usage examples

 <Avatar src="/avatar.jpg" />  <Avatar src={User} />  <Avatar fallbackSeed={user.id} aria-label={user.name} />  <Avatar fallbackColor="purple" aria-label="SnowUI member" />  <Avatar />  <Avatar gradientMotion />  <Avatar variant="empty" />  <Avatar fallback={GradientMotion} data-name="Ada Lovelace" />  <Avatar>    <GradientMotion as="avatar-image" variant="random" seed="profile-42" />    <Badge as="badge" dot /></Avatar>  <Avatar src="/avatar.jpg">    <Badge as="badge" dot /></Avatar>

Intelligent behavior

  1. Default fallback: Without an image or after a load failure, an explicit fallback component takes priority. Otherwise, default uses Gradient and empty uses a gray user icon. Default Gradient selection is fallbackColor → fallbackSeed → aria-label / data-name / title → fixed blue. Pass a stable user.id as fallbackSeed; its hash stays stable across reloads, so no color field is needed. Names serve only as compatibility seeds, not generated initials. Base Gradient deformation is off by default; enable it with gradientMotion or run it on hover.

  2. Fallback delay: A fixed internal delay before showing the fallback reduces loading flicker.

  3. Role detection: A child Badge or Icon with as="badge" receives badge positioning and sizing automatically.

  4. Child positioning: Adaptive em-based styling uses the component context.

  5. Resolution selection: Avatar passes its resolved size to resource components such as AvatarByewind, allowing them to choose a high-resolution 3× image (for example, 240px for an 80px avatar).

  6. Default hover: Each hover of a non-disabled image or ordinary component avatar randomly selects blue, cyan, green, red, orange, or purple and overlays color only on the actual graphic alpha layer. Gradient fallback retains its five-color cycle whether base deformation is on or off, and runs its four ripple layers at their respective periods on demand.

The six-color hover overlay for images and ordinary component fallbacks is Avatar’s registered artistic-color exception under specs/maintainers/StyleSpec.md §2.1.3. Avatar owns these private hover colors; they are not general SnowUI tokens. The default Gradient art is owned by Gradient, and a fallback GradientMotion owns its shader colors. These exceptions do not extend to Avatar sizing, layout, normal backgrounds, states, public color props, or style priority.

Avatar style overlay

Read the complete LICENSE first; one review covers the same task, version, and scope.

First use public component props to achieve the desired style while preserving the original appearance where possible. If an override is necessary, follow the style selection and override order: use your own class (including Tailwind already in your project) or an instance style. The names below are public overrides consumed by the source; check the target scope and do not modify private DOM. Choose the appropriate SnowUI token category. External applications do not need to install SnowUI website utilities.

Variable Purpose and default reference
--snowui-avatar-default-icon-size-override Default icon size (size px, see the component source code for the default value)
--snowui-avatar-size-override Overall size (size px, see the component source code for the default value)

Design Guide · Token · Combination boundary

Avatar type and status

Required props: no named required props.

Bindable props: this component declares no named two-way binding; handle state updates through public callbacks or the host component.

Inheritance: FrameProps. Consult the public Frame documentation for inherited capabilities.

Shared Frame API · Back to API

The following source type declarations are referenced by public props. Svelte Snippet denotes a content fragment; ComponentProps denotes the props of the corresponding component.

ResourceSize

Source: components/src/context.ts

export type ResourceSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;

GradientVariant

Source: components/src/components/Gradient.svelte

export type GradientVariant =        | "blue"        | "cyan"        | "green"        | "red"        | "orange"        | "purple";

AvatarVariant

Source: components/src/components/Avatar.svelte

type AvatarVariant = "default" | "empty";