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';

Props​

PropTypeDefaultDescription
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).
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.
color'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white'—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.
classNamestring—Additional CSS classes.
...All standard HTML and Bulma helper props(See Helper Props)

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.
  • 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​