components / 19

marked avatar

identity stays photographic. the hand belongs around it, behind the fallback, and wherever presence needs saying.

shadcnnpx shadcn@latest add berkantay/cheez/marked-avatar

live

playground

image idle

online

Berkant Aydesigning Cheez in publicsuccess: online

use photo

shape

size

character

presence

presence corner

frame

frame ink

<MarkedAvatar
  name="Berkant Ay"
  src="/images/jpeg/me.jpg"
  shape="circle"
  size="xlarge"
  character="rushed"
  frameMark="loose-circle"
  frameColor="#f4f0e6"
  status="online"
  statusPosition="bottom-right"
/>

source

image or fallback

Base UI owns the loading state

loaded image

generated initials

failed image

custom fallback

scale

four deliberate sizes

32 to 84 pixels

smallonline

mediumaway

largebusy

xlargeoffline

perimeter

shape changes the hand

clip and frame move together

circleonline

roundedaway

squarebusy

presence

no generic status dots

shape, color, and spoken label

online

Berkant Ayavailable now

success: online

away

Maya Chenback soon

warning: away

busy

Noah Williamsdo not disturb

error: busy

offline

Ari Okafornot connected

offline

composition

teams and overflow

one accessible group

onlineawaybusyoffline

Cheez maintainers4 shown · 8 more

reference

api

avatar and group

prop	type	default	purpose
`name`	`string`	`required`	fallback identity and default image alt
`src`	`string`	`—`	image source
`alt`	`string`	`name`	image alternative text
`fallback`	`ReactNode`	`initials`	custom fallback content
`fallbackDelay`	`number`	`0`	delay before fallback appears
`initialsLength`	`number`	`2`	generated fallback length
`fallbackMark`	`CheezType`	`"spotlight"`	fallback marker wash
`fallbackColor`	`string`	`"#8f74ff"`	fallback marker ink
`shape`	`"circle" \| "rounded" \| "square"`	`"circle"`	image clipping and default frame
`size`	`"small" \| "medium" \| "large" \| "xlarge"`	`"medium"`	avatar dimensions
`frameMark`	`CheezType`	`shape-aware`	perimeter override
`frameColor`	`string`	`"#f4f0e6"`	perimeter ink
`character`	`CheezCharacter`	`"rushed"`	drawing personality
`thickness`	`number`	`1`	pen weight
`status`	`MarkedAvatarStatus`	`—`	presence glyph
`statusPosition`	`four corners`	`"bottom-right"`	presence placement
`statusMark`	`CheezType`	`status-aware`	presence glyph override
`statusColor`	`string`	`status-aware`	presence ink override
`statusLabel`	`string`	`status name`	accessible presence text
`announceStatus`	`boolean`	`true`	include hidden presence label
`imageProps`	`AvatarImageProps`	`—`	responsive image and loading props
`onLoadingStatusChange`	`function`	`—`	idle/loading/loaded/error callback
`Group.overflow`	`number`	`0`	additional people count
`Group.overflowLabel`	`string`	`N more people`	accessible overflow name
`Group.countMark`	`CheezType`	`"loose-circle"`	overflow boundary
`Group.label`	`string`	`"people"`	group accessible name

behavior notes

Base UI swaps the image and fallback according to real loading status
fallback initials are decorative; the full name remains available to assistive technology
presence uses a drawn symbol plus hidden text instead of relying on color
the avatar itself is not interactive; wrap it in an appropriately labelled button when it opens a menu
imageProps supports srcSet, sizes, crossOrigin, referrerPolicy, and native image attributes
group overflow is announced as a count while the visible form stays compact