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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import Avatar primitives from @/components/kamod-ui/avatar.
pnpm add @kamod-ch/uiCopy 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 { 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 { Avatar } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthComponent 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthGenerated 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAnimated 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthBadge
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthBadge 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAvatar 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAvatar 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthGroup 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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSizes
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 preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDropdown
Treat the Avatar as an Account-Menu Trigger. Wrap the avatar in a ghost-style icon button and use that button as the dropdown trigger. The photo identifies the account while the button provides the focusable target for its related actions.
Group account actions clearly in the Dropdown, and make switching accounts distinct from signing out.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSmartAvatar 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.
pnpm add blobatar @blobatar/preactSmartAvatar (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.
| Prop / type | Description |
|---|---|
name | Configure
|
src | Configure
|
label | Configure
|
badge | Configure
|
blobatar | Configure
|
size | Configure
|
class | Configure
|
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.
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
? 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.Avatar
AvatarProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
size | Configure
|
AvatarBadge
AvatarBadgeProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
AvatarFallback
AvatarFallbackProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
AvatarGroup
AvatarGroupProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
AvatarGroupCount
AvatarGroupCountProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
AvatarImage
AvatarImageProps
| Prop / type | Description |
|---|---|
alt | Configure
|
class | Configure
|
onError | Configure
|
onLoad | Configure
|
src | Configure
|
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 fieldsAvatarPropsAvatar.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 fieldAvatarBadgePropsAvatarBadge.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 fieldAvatarFallbackPropsAvatarFallback.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 fieldAvatarGroupPropsAvatarGroup.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 fieldAvatarGroupCountPropsAvatarGroupCount.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
DeclarationAvatarImagePropsAvatarImage.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 fieldsAvatarContextValuetypes.ts. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of AvatarContextValue before adapting it.notifyLoad, notifyError, resetImage, showFallbackAccessibility
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.
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.