Display@knitui/components
Avatar
Avatar is a circular display element built from Box + Text. It renders an image when src is provided, falls back to initials derived from name, or shows custom children as the placeholder. autoColor automatically assigns a theme accent by hashing the name. Use Avatar.Group to stack overlapping avatars.
import { Avatar } from "@knitui/components";Playground
Loading playground…
<Avatar
name="Jane Doe"
variant="light"
size="md"
autoColor
/>Examples
Variants
Every visual variant side by side, at the default size.
Loading example…
Sizes
The seven token sizes, from xxs to xxl.
Loading example…
Shadows
Elevation via the shared shadow ladder — inherited from Box, so every component accepts it; no shadow unless set.
Loading example…
With Initials
Initials are derived from the name — one word gives up to two letters, two+ words give the first letter of each.
Loading example…
Auto Color
Each avatar auto-selects a distinct accent color by hashing its name — no manual theme needed.
Loading example…
With Image
An image is rendered clipped to the avatar circle; if loading fails the initials placeholder is shown.
Loading example…
Custom Placeholder
Custom children are used as the placeholder instead of initials.
Loading example…
Group
Avatar.Group stacks avatars with overlap; spacing controls the overlap distance in px.
Loading example…
Matrix
Full variant × size matrix for visual regression.
Loading example…
Gradient
Gradient fills — the themed default ramp, a two-color shorthand, a token gradient, and a multi-step stops gradient.
Loading example…
Gradient Presets
A handful of curated gradient presets — both two-color and multi-step.
Loading example…
Gradient Themed
With no gradient prop, variant="gradient" falls back to the active theme's ramp.
Loading example…
Gradient Sizes
A gradient fill across the seven token sizes.
Loading example…
Gradient Group
Avatar.Group stacks gradient avatars — each with a distinct preset and initials.
Loading example…
Styles
Per-slot styles targets individual parts — here the root frame and text initials.
Loading example…
Props
| Prop | Type | Default | Description |
|---|---|---|---|
allowedInitialsColors | readonly string[] | undefined | — | Subset of accent colors eligible for auto-color assignment. Defaults to all available accent themes. Mirrors Mantine's `allowedInitialsColors`. |
alt | string | undefined | — | Accessible label for the avatar image role. |
autoColor | boolean | undefined | true | Automatically selects a theme accent by hashing the name when no explicit theme is set. |
disabled system | boolean | undefined | — | |
gradient system | GradientValue | undefined | — | Gradient fill for variant='gradient' — { from, to, deg } or { stops, deg }. |
name | string | undefined | Jane Doe | User name — rendered as initials when no image is present. |
radius system | string | number | undefined | — | |
shadow system | "xs" | "sm" | "md" | "lg" | "xl" | "xxs" | "xxl" | undefined | — | |
size system | string | number | undefinedxxs · xs · sm · md · lg · xl · xxl | md | Controls the diameter and initials font size. |
src | string | null | undefined | — | Image URL. Falls back to initials or children on error. |
styles system | SlotStyles<AvatarStyles> | undefined | — | Per-slot style sugar — props spread onto the matching styled part. |
theme system | ThemeName | null | undefinedunset · blue · red · green · orange · pink · purple · teal · yellow · gray | — | Explicit accent theme — overrides autoColor. |
variant system | "light" | "outline" | "white" | "transparent" | "default" | "filled" | "gradient" | undefinedfilled · light · outline · transparent · default · white · gradient | light | Visual variant — how the theme color ramp is applied. |
Style slots
Every part of Avatar can be styled through the styles prop. Explicit props on the component always win over slot styles.
| Slot | Usage |
|---|---|
image | styles={{ image: { … } }} |
root | styles={{ root: { … } }} |
text | styles={{ text: { … } }} |
Accessibility & DOM props (2)
| Prop | Type |
|---|---|
key | Key | null | undefined |
ref | Ref<TamaguiElement> | undefined |
Plus 500 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.