Components

Avatar

Identifies a person or company with a picture, or with initials when there is none, and an optional status dot.

Storybook: Storybook
Source: Source

Installation

Package: @bigbang/ui
Import: import { Avatar } from '@bigbang/ui';
Source: Avatar.tsx
Storybook: Avatar · Playground

Avatar is in the @bigbang/ui package. Installation and style files are the same as for Button; see the Button code tab.

import { Avatar } from '@bigbang/ui';

<Avatar name="User 1" src="/people/user-1.png" status="online" />;

The part prop types are exported too: AvatarImageProps, AvatarFallbackProps, AvatarStatusProps, AvatarGroupProps.

Props

src

Description: Image address. While it loads, or if it fails, the fallback shows. Omit it to show the fallback only.
Type: string

nameRequired

Description: Full name of the person or the company. It is the accessible name and gives the initials and the fallback colour. An empty string shows a placeholder icon.
Type: string

kind

Description: Person or company. A company is a rounded square by default and gets a building placeholder when it has no name.
Type: Kind
Default: 'person'

size

Description: 24, 32, 40, 48 or 64 px.
Type: Size
Default: 'sm'

shape

Description: Circle or rounded square (radius-md). Defaults to circle for a person and square for a company.
Type: 'circle' | 'square'
Default: 'circle'

status

Description: Presence dot at the bottom inline end, with a 2 px surface ring. The state is also part of the accessible name, for example "User 1 (online)".
Type: Status

decorative

Description: Hides the avatar from screen readers. Use it when the name is printed beside it, so it is not read twice. The status is then not announced either.
Type: boolean
Default: false

delay

Description: Milliseconds to wait before the fallback shows while an image loads, which avoids a flash of initials on fast connections.
Type: number

onLoadingStatusChange

Description: Called when the image is idle, loading, loaded or error.
Type: (status: 'idle' | 'loading' | 'loaded' | 'error') => void

className

Description: For layout only: margins and alignment. Do not use it to change the size or colour.
Type: string

children

Description: Custom parts (Avatar.Image, Avatar.Fallback, Avatar.Status). Without it the avatar builds them from the props.
Type: ReactNode

Native attributes (id, data-*) pass through to the root element. role, aria-label and aria-hidden are set by Avatar.

Parts

Part	Element	Props
`Avatar.Image`	`<img>`	`src` (default: the `src` of the Avatar) and native image attributes. `alt` is empty.
`Avatar.Fallback`	`<span>`	`children`: replaces the initials and the icon.
`Avatar.Status`	`<span>`	`status` (default: the `status` of the Avatar). Hidden from screen readers.
`Avatar.Group`	`<div>`	`max`, `size`, `className`, `aria-label`. Role `group`; a “+N” count for the rest.

With children, Avatar does not draw its own image, fallback and status; you compose the parts.

Data attributes

data-component="avatar", data-kind, data-size, data-shape: on the root. The group carries data-component="avatar-group".
data-part: image, fallback, status, count. The status dot also carries data-status.

Language

The initials are upper-cased with the rules of the Provider language; without a Provider Turkish is used. The status, person, company and count names are the ui.avatar.* strings.

import { Avatar, Provider } from '@bigbang/ui';

<Provider locale="en-GB">
  <Avatar name="User 1" status="busy" />
</Provider>;