DisplayReact

Avatar

An easily stylable avatar: the person's picture, with initials or an icon in its place while the image loads or when it fails.

Rendered by React 19.3.1

import { Avatar } from '@hamur/react/avatar'

// Inline images keep the example off the network; use your own URLs in an app.
const photo =
  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%232457d6'/%3E%3Ccircle cx='20' cy='16' r='7' fill='white'/%3E%3Cpath d='M6 40a14 14 0 0 1 28 0' fill='white'/%3E%3C/svg%3E"
const missing = 'data:text/plain,not-an-image'

export default function AvatarExample() {
  return (
    <div className="stack">
      <div className="row">
        <Avatar.Root className="profile">
          <Avatar.Image
            className="profile-image"
            src={photo}
            alt="Ada Lovelace"
          />
          <Avatar.Fallback className="profile-fallback">
            AL
          </Avatar.Fallback>
        </Avatar.Root>
        <Avatar.Root className="profile">
          <Avatar.Image
            className="profile-image"
            src={missing}
            alt="Grace Hopper"
          />
          <Avatar.Fallback className="profile-fallback">
            GH
          </Avatar.Fallback>
        </Avatar.Root>
        <Avatar.Root className="profile">
          <Avatar.Fallback className="profile-fallback" delay={600}>
            KJ
          </Avatar.Fallback>
        </Avatar.Root>
      </div>
      <p className="muted">
        The first image loads, the second fails and shows initials, the third has no image and shows
        its initials after 600 ms.
      </p>
    </div>
  )
}

122Tests passing in React · 0 failing

5.3 KiBSize

Not measured yetMemory

Not measured yetSpeed

productdevbook and 13 upstream authors9 commits · last Nov 4

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Avatar.Root>
  <Avatar.Image />
  <Avatar.Fallback />
</Avatar.Root>

Examples

The demo at the top is the one example this component has so far.

API reference

3 props across 3 parts, in React syntax. className, style, render are listed once, under Shared props.

Fallback`Avatar.Fallback`

Rendered when the image fails to load or when no image is provided. Renders a <span>.

Fallback props
Prop	Type	Default
`delay`How long to wait before showing the fallback.	`number`	`0`

Image`Avatar.Image`

The image to be displayed in the avatar. Renders an <img>.

Image props
Prop	Type	Default
`onLoadingStatusChange`Callback fired when the loading status changes.	`((status: ImageLoadingStatus) => void)`	`—`
`keepMounted`Whether the image element stays mounted and loads in place instead of being preloaded.	`boolean`	`false`

Image data attributes
Data attribute	Description
`data-loading`	Present while the image is loading.
`data-error`	Present when the image failed to load.
`data-starting-style`	Present when the image begins animating in.
`data-ending-style`	Present when the image is animating out.

Root`Avatar.Root`

Displays a user's profile picture, initials, or fallback icon. Renders a <span>.

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Avatar takes no focus and has no keys of its own.

Accessibility

What the parts set
Part	Sets	So that
Image	renders an `<img>`, with the `alt` you give it	the picture has a text alternative
Image	`aria-hidden="true"` until the image has loaded	a screen reader does not read an image that is not there
Fallback	renders a `<span>` with your content	initials or a label stand in when there is no image

Focus order

Avatar is not focusable; focus passes over it.