Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

Media & Presentation

Avatar

Profile image with initials fallback, status badge, overlapping groups, count chip, sizes, and dropdown trigger (shadcn Avatar pattern; no Radix dependency). Give media a predictable place in the layout while keeping the surrounding content readable during loading, playback or failure. Import it from @/components/kamod-ui/avatar.

Source · Design reference · API reference · Theming · Styles


Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Installation

Import Avatar primitives from @/components/kamod-ui/avatar.

Install PackagesTerminal
pnpm add @kamod-ch/ui

Copy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.

Import SetupTypeScript
import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from "@kamod-ch/ui";

Usage

Place AvatarImage and AvatarFallback inside Avatar. The fallback stays visible until the image fires load; on error it shows again.

Import SetupTypeScript
import { Avatar } from "@kamod-ch/ui";

Choose a complete composition from the examples below; required child components and props vary by pattern.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Component Examples & Variants

Explore Avatar in Different Contexts, from the starting pattern to the compositions below. Begin with Basic, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.

Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.

Basic

Plan for Missing or Slow Images. Provide a photo through AvatarImage and a recognizable alternative through AvatarFallback. The fallback gives the identity a stable visual representation when the photo is missing or cannot be displayed.

An avatar is a compact identity cue; it should not be the only way to distinguish important people or account actions.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Generated Fallback

Keep Generated Identities Stable. The optional SmartAvatar recipe derives a repeatable blobatar from a stable user identifier. Install blobatar separately and copy the recipe when this fallback is useful; the core Avatar remains the underlying primitive.

Review the SmartAvatar Recipe before adoption, then check a missing photo, a failed URL and a slow connection. Use the same user identifier across renders so those situations do not unexpectedly change someone's visual identity.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Animated Fallback

Use Motion as an Optional Enhancement. Enable blobatar.animate="hover" in the optional recipe and import blobatar/motion.css once in your stylesheet. This adds movement to the generated fallback without requiring animation for ordinary photos or static avatars.

Apply animation only where it adds personality without distracting from a list of names, and avoid loading motion styles if the application uses only static avatars.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Badge

Pair Presence with an Understandable Status. Add AvatarBadge to place a status marker at the photo's bottom inline edge. Its separating ring helps the overlapping marker remain distinct from the image; the surrounding text should explain what that status means.

Add an accessible or nearby text description when status matters, and check that the badge remains distinct against both the photo and the surrounding surface.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Badge with Icon

Use a Symbol for a Specific Status. Put a recognizable symbol inside AvatarBadge when a plain status dot is insufficient. The small avatar treatment hides the inner SVG to avoid crowding, so the symbol must not carry essential information alone.

Provide a nearby text equivalent for meaningful status and test the smallest size before choosing a symbol. Distinguish that account state from identity: the avatar should still identify the person when there is no room for the badge graphic.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Avatar Group

Show a Collection without Hiding Its Meaning. Wrap related avatars in AvatarGroup to overlap their edges while keeping a ring between neighboring images. This presents a compact group of people without requiring a separate labeled row for each person.

Keep the order stable and provide another way to inspect names; if each avatar is interactive, verify that overlapping surfaces do not make its target difficult to reach.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Avatar Group Count

Make Overflow Informative. Append AvatarGroupCount after the visible avatars to show how many people are omitted. Derive the +N label from the same collection that supplies the photos so the summary remains accurate.

If the count opens a participant list, use a real control with a descriptive accessible name rather than making a decorative bubble unexpectedly interactive.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Group Count with Icon

Distinguish Overflow from Adding a Person. An icon inside AvatarGroupCount can suggest more participants or a group action. Pair the visual shorthand with a meaningful accessible name whenever the surrounding composition makes it an interactive control.

Keep a numeric or textual explanation available when the size of the group matters to the reader.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

Sizes

Match the Avatar to Its Role. Choose size="sm", the default size or size="lg" on Avatar to match its context. The comparison shows how the image, fallback and badge share the same overall density choice.

Check photo crops, fallback initials and badges at each size rather than scaling only the image; the accompanying name should remain the primary readable identity.

Interactive Live Preview
Try it. Make it yours.
Setting the scene...

Interactive preview

Live Preact example Local preview theme · Responsive styles follow the preview widthFull width

SmartAvatar Recipe (Optional)

Adopt the Recipe Deliberately. Use the docs' SmartAvatar recipe when generated fallbacks belong in your application. It composes Kamod primitives with a separate third-party package; copying it does not add blobatar behavior to the core Avatar API.

Choose a stable seed, a readable initials fallback and an appropriate loading strategy; verify the result when remote photos fail rather than testing only successful images.

Install PackagesTerminal
pnpm add blobatar @blobatar/preact

SmartAvatar (Docs Recipe)

Optional composition in packages/docs/src/docs/examples/avatar/SmartAvatar.tsx. Depends on blobatar and @blobatar/preact — not shipped with @kamod-ch/ui.

SmartAvatar (docs recipe) documented props
Prop / typeDescription
name
string

Configure name for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
required (blobatar seed)
src
string | null

Configure src for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
undefined
label
string

Configure label for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
undefined
badge
ComponentChildren

Configure badge for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
undefined
blobatar
SmartAvatarBlobatarOptions

Configure blobatar for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
undefined
size
"sm" | "default" | "lg"

Configure size for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
"default"
class
string

Configure class for SmartAvatar (docs recipe). Compare its accepted type with the Usage Guidance before supplying a value.

Default
-
API reference

Props and Data

Configure Avatar using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.

@kamod-ch/ui Avatar primitives.

API reference
Your API, from source

Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.

Component Props

Read each option with its owning component. The
marker identifies required fields verified in that declaration. A ? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.
@kamod-ch/ui/avatar7.1 KB min · 2.1 KB gzipSignals: none

Avatar

AvatarProps

Avatar documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildAvatarProps

Configure children for Avatar. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>AvatarProps

Configure class for Avatar. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
size
"default" | "sm" | "lg"AvatarProps

Configure size for Avatar. Compare its accepted type with the Usage Guidance before supplying a value.

Default
"default"

AvatarBadge

AvatarBadgeProps

AvatarBadge documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildAvatarBadgeProps

Configure children for AvatarBadge. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>AvatarBadgeProps

Configure class for AvatarBadge. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

AvatarFallback

AvatarFallbackProps

AvatarFallback documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildAvatarFallbackProps

Configure children for AvatarFallback. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>AvatarFallbackProps

Configure class for AvatarFallback. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

AvatarGroup

AvatarGroupProps

AvatarGroup documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildAvatarGroupProps

Configure children for AvatarGroup. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>AvatarGroupProps

Configure class for AvatarGroup. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

AvatarGroupCount

AvatarGroupCountProps

AvatarGroupCount documented props
Prop / typeDescription
children
ComponentChild[] | ComponentChildAvatarGroupCountProps

Configure children for AvatarGroupCount. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
class
string | SignalLike<string | undefined>AvatarGroupCountProps

Configure class for AvatarGroupCount. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

AvatarImage

AvatarImageProps

AvatarImage documented props
Prop / typeDescription
alt
string | SignalLike<string | undefined>AvatarImageProps

Configure alt for AvatarImage. Compare its accepted type with the Usage Guidance before supplying a value.

Default
""
class
string | SignalLike<string | undefined>AvatarImageProps

Configure class for AvatarImage. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onError
GenericEventHandler<HTMLImageElement>AvatarImageProps

Configure onError for AvatarImage. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
onLoad
GenericEventHandler<HTMLImageElement>AvatarImageProps

Configure onLoad for AvatarImage. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—
src
string | SignalLike<string | undefined>AvatarImageProps

Configure src for AvatarImage. Compare its accepted type with the Usage Guidance before supplying a value.

Default
—

Data Type Reference

Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.

Avatar Props

2 declared fields
AvatarProps
Exported Source Declaration from Avatar.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarProps before adapting it.

AvatarBadge Props

1 declared field
AvatarBadgeProps
Exported Source Declaration from AvatarBadge.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarBadgeProps before adapting it.

AvatarFallback Props

1 declared field
AvatarFallbackProps
Exported Source Declaration from AvatarFallback.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarFallbackProps before adapting it.

AvatarGroup Props

1 declared field
AvatarGroupProps
Exported Source Declaration from AvatarGroup.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarGroupProps before adapting it.

AvatarGroupCount Props

1 declared field
AvatarGroupCountProps
Exported Source Declaration from AvatarGroupCount.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarGroupCountProps before adapting it.

AvatarImage Props

Declaration
AvatarImageProps
Exported Source Declaration from AvatarImage.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarImageProps before adapting it.

AvatarContextValue

4 declared fields
AvatarContextValue
Exported Source Declaration from types.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarContextValue before adapting it.
Required fields
notifyLoad, notifyError, resetImage, showFallback

Accessibility

AvatarImage defaults to an empty alt value and coordinates loading/failure with the fallback. An avatar is decorative when the same identity is already conveyed nearby, but informative when it is the only representation of a person.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.