Skip to main content

Avatar

Overview​

The Avatar component represents a person or entity as a compact image.

It falls back automatically from a photo (src) to initials (from name/initials) to a custom icon, and finally to a generic default icon — so you never have to hand-roll the broken-image or missing-photo case.

Import​

import { Avatar } from '@allxsmith/bestax-bulma';

Usage​

Photo with Automatic Fallback​

A working photo renders as an image; if the src fails to load, Avatar swaps to initials derived from name automatically — no broken-image icon.

<Avatars spaced>
  <Avatar src="https://github.com/allxsmith.png" name="Al Smith" size="64x64" />
  <Avatar
    src="https://example.invalid/missing.jpg"
    name="Grace Hopper"
    size="64x64"
  />
</Avatars>

Initials​

With no src, initials render on a deterministic auto background color derived from name.

<Avatars spaced>
  <Avatar name="Ada Lovelace" />
  <Avatar name="Grace Hopper" />
  <Avatar name="Katherine Johnson" />
</Avatars>

Icon Fallback​

Pass an icon to control the final fallback when there is no photo, name, or initials.

<Avatar icon={<Icon name="user" />} color="info" shape="rounded" />

Shapes​

The shape prop switches between a circle, a rounded square, and a plain square.

<Avatars spaced>
  <Avatar name="Circle" shape="circle" />
  <Avatar name="Rounded" shape="rounded" />
  <Avatar name="Square" shape="square" />
</Avatars>

Sizes​

Preset sizes mirror Image's fixed-size list; a number renders a pixel size.

<Avatars spaced>
  <Avatar name="Ada Lovelace" size="24x24" />
  <Avatar name="Ada Lovelace" size="32x32" />
  <Avatar name="Ada Lovelace" size="48x48" />
  <Avatar name="Ada Lovelace" size="64x64" />
  <Avatar name="Ada Lovelace" size={20} />
</Avatars>

Clickable Avatar​

Set href to render the avatar as a link (or pass as for a custom element).

<Avatar name="Ada Lovelace" href="https://bestax.io" />

Forwarding Props to the Image​

imageProps is spread onto the underlying <img> — handy for native attributes like loading, crossOrigin, or referrerPolicy. A custom onError is chained before the automatic initials/icon fallback runs.

<Avatar
  src="https://github.com/allxsmith.png"
  name="Al Smith"
  size="64x64"
  imageProps={{ loading: 'lazy' }}
/>

Accessibility​

  • Image avatars use alt (falling back to name) for their accessible name.
  • Initials/icon avatars expose role="img" and aria-label (from alt/name) — unless rendered as a link or button, where the native link/button role and aria-label are used instead.
  • Decorative avatars: pass an explicit alt="" when the avatar repeats information already visible next to it (e.g. beside the author's name in a comment row). The image stays decorative and an initials/icon avatar is skipped entirely (aria-hidden), avoiding double-speak. The opt-out never applies to a link/button avatar — an interactive element always keeps an accessible name (from name, or a generic "Avatar" fallback).
  • A link/button avatar with no alt/name (e.g. an API that returns only a photo URL) still gets an aria-label fallback rather than rendering a nameless control.
  • as="button" defaults to type="button", so a clickable avatar inside a form doesn't submit it.
  • The default fallback icon is aria-hidden.
  • Avatars: An overlapping group of Avatars with a "+N" surplus bubble.
  • Badge: A status/count indicator that overlays an Avatar (or any element).
  • Image: Bulma's fixed-ratio image container.
  • Helper Props: Bulma helper props for spacing, color, etc.

Additional Resources​

Props​

PropTypeDefaultDescription
classNamestring—Additional CSS classes to apply.
srcstring—Image URL. On load error (or if absent), falls back to initials, then icon.
altstring—Alternate text for the image (used for the accessible name in every render mode). An explicit alt="" marks a non-interactive avatar as decorative.
namestring—Derives initials and a deterministic background color when no src is shown.
initialsstring—Explicit initials override (else derived from name).
iconReact.ReactNode—Final fallback, rendered when there is no src, name, or initials.
size'16x16' | '24x24' | '32x32' | '48x48' | '64x64' | '96x96' | '128x128' | number—Preset size, or a pixel size when a number.
shape'circle' | 'rounded' | 'square''circle'Avatar shape. Default 'circle'.
colorAvatarColor—Background color for initials/icon avatars (else auto-derived from name).
asReact.ElementType—Element/component to render as. Defaults to 'a' when href is set, else 'figure'.
hrefstring—When set, renders the avatar as a link.
targetstring—Anchor target — forwarded only when rendering a link (an a or a custom as component).
relstring—Anchor rel — forwarded only when rendering a link (an a or a custom as component).
imagePropsReact.ImgHTMLAttributes<HTMLImageElement>—Extra props forwarded to the underlying <img> (e.g. loading, crossOrigin); its onError is chained before the fallback fires.
...All standard HTML attributes and Bulma helper props—See Helper Props

Types:

  • AvatarColor: 'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white' — Valid color values for the Avatar component.

CSS & Sass Variables​

Avatar registers these variables on its own .avatar element. Override them there (or via className) — a value set on an ancestor is only inherited, and loses to the component-level declaration. See Theme.

CSS VariableSass VariableDefault
--bulma-avatar-size$avatar-size48px
--bulma-avatar-background$avatar-backgroundvar(--bulma-background)
--bulma-avatar-color$avatar-colorvar(--bulma-text)
--bulma-avatar-weight$avatar-weightvar(--bulma-weight-semibold)
--bulma-avatar-rounded-radius$avatar-rounded-radiusvar(--bulma-radius-large)