Avatar

Show a user as initials, an icon or an image, with an optional presence dot.

Avatar is a client component ("use client") that renders a circular Box containing initials, an icon or a next/image image. Use it to represent people or accounts in lists, headers and comments. It depends on Next.js (next/image) and the Icon block for string icon names.

Import#

typescript

import { Avatar } from "@reactberry/system/blocks";

Usage#

typescript

import { Avatar } from "@reactberry/system/blocks";
import { Box, Text } from "@reactberry/system/elements";

export default function MemberRow() {
  return (
    <Box display="flex" alignItems="center" gap="s">
      <Avatar
        type="image"
        name="Ada Lovelace"
        src="https://example.com/avatars/ada.jpg"
        size="2rem"
        withPresence
      />
      <Text fontWeight="600">Ada Lovelace</Text>
    </Box>
  );
}

Examples#

Fixed colour#

By default the colour is derived from name. Set autocolor={false} and pass color to use one colour for everyone.

Grace Hopper

Alan Turing

Katherine Johnson

Image fallback#

When type="image" has no src, or the image fails to load, fallbackType decides what renders instead: initials ("text") or the silhouette ("icon", the default).

Presence status#

Set withPresence to show a dot. status sets its colour and border. The dot has no text, so show the status next to the avatar.

Ada LovelaceOnline

Alan TuringAway

Grace HopperBusy

API#

Avatar#

Prop	Type	Default	Description
`type`	`"text" \| "icon" \| "image"`	`"text"`	What to render inside the circle.
`name`	`string`	`"Aa"`	Source for the initials and the auto colour; also used as the image `alt` fallback.
`autocolor`	`boolean`	`true`	Derives the colour from `name` via a string hash.
`color`	`string`	—	Colour used when `autocolor` is `false`. Falls back to `"neutral"`.
`size`	`string`	`"2.5rem"`	Width and height of the circle.
`fontSize`	`string`	`"75%"`	Initials font size.
`src`	`string`	—	Image URL for `type="image"`.
`alt`	`string`	—	Image alt text. Falls back to `name`, then `"avatar"`.
`fallbackType`	`"text" \| "icon"`	`"icon"`	Rendered when `type="image"` has no `src` or the image fails to load.
`icon`	`string \| ComponentType \| ReactElement`	—	Icon for `type="icon"`: a registered icon name, a component, or a rendered element. Without it, a user silhouette is drawn.
`iconProps`	`object`	`{}`	Forwarded to the icon when `icon` is a name or component.
`withPresence`	`boolean`	`false`	Shows the status dot.
`status`	`{ label: string; color: string; border: string; size?: string } \| null`	`{ label: "online", color…`	Dot colour (`color`), border colour (`border`) and optional `size`.
`statusProps`	`object`	`{}`	Spread onto the status dot `Box`.

All other props are spread onto the inner circle Box, after the defaults (display="inline-flex", shape="circle", overflow="hidden", flex="none"). The prop type includes [key: string]: any, so unknown props are not type-checked.

Accessibility#

The avatar renders div elements with no role or label. Initials are plain text and are read by screen readers.
The silhouette and icons have no accessible name.
Images use alt, then name, then "avatar" as alt text.
status.label is declared but not rendered or used for accessibility. Add an accessible label yourself if presence matters.

Notes#

Initials are the first letters of the first two space-separated words, or the first two characters of a single word, upper-cased.
The circle background uses currentColor, so color (or the auto colour) sets the fill; initials and icons are white.
Failed image URLs are remembered for the session by URL without its query string, so presigned URLs that only change their signature are not retried.
Remote src hosts must be allowed in your Next.js images configuration.
The status dot size is calc(status.size or size / 2.5) when size is passed, otherwise "0.625rem" regardless of status.size.
name is also forwarded to the inner div as a name attribute.