Avatar

The Avatar component is a React component that represents a user avatar or profile picture. It displays an image or initials within container.

Avatar provides support for fallback text or elements when the image fails to load, or when the image is not provided.

0.78.1 (latest)

Visualize Logic

View Source

Properties

name

src

Installation

To use the avatar machine in your project, run the following command in your command line:

npm install @zag-js/avatar @zag-js/react
# or
yarn add @zag-js/avatar @zag-js/react

npm install @zag-js/avatar @zag-js/solid
# or
yarn add @zag-js/avatar @zag-js/solid

npm install @zag-js/avatar @zag-js/vue
# or
yarn add @zag-js/avatar @zag-js/vue

npm install @zag-js/avatar @zag-js/svelte
# or
yarn add @zag-js/avatar @zag-js/svelte

This command will install the framework agnostic avatar logic and the reactive utilities for your framework of choice.

Anatomy

To set up the avatar correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Usage

First, import the avatar package into your project

import * as avatar from "@zag-js/avatar"

The avatar package exports two key functions:

machine — The state machine logic for the avatar widget.
connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll also need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the avatar machine in your project 🔥

import * as avatar from "@zag-js/avatar"
import { useMachine, normalizeProps } from "@zag-js/react"

function Avatar() {
  const [state, send] = useMachine(avatar.machine({ id: "1" }))

  const api = avatar.connect(state, send, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <span {...api.getFallbackProps()}>PA</span>
      <img alt="PA" src={src} {...api.getImageProps()} />
    </div>
  )
}

import * as avatar from "@zag-js/avatar"
import { useMachine, normalizeProps } from "@zag-js/solid"

function Avatar() {
  const [state, send] = useMachine(avatar.machine({ id: "1" }))

  const api = createMemo(() => avatar.connect(state, send, normalizeProps))

  return (
    <div {...api.getRootProps()}>
      <span {...api.getFallbackProps()}>PA</span>
      <img alt="PA" src={src} {...api.getImageProps()} />
    </div>
  )
}

<script setup>
  import * as avatar from "@zag-js/avatar"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed } from "vue"

  const [state, send] = useMachine(avatar.machine({ id: "1" }))

  const api = computed(() => avatar.connect(state.value, send, normalizeProps))
</script>

<template>
  <div v-bind="api.getRootProps()">
    <span v-bind="api.getFallbackProps()">PA</span>
    <img alt="PA" :src="src" v-bind="api.getImageProps()" />
  </div>
</template>

<script lang="ts">
  import * as avatar from "@zag-js/avatar"
  import { useMachine, normalizeProps } from "@zag-js/svelte"

  const [snapshot, send] = useMachine(avatar.machine({ id: "1" }))
  const api = $derived(avatar.connect(snapshot, send, normalizeProps))
</script>

<div {...api.getRootProps()}>
  <span {...api.getFallbackProps()}>PA</span>
  <img alt="PA" src={src} {...api.getImageProps()} />
</div>

Listening for loading status changes

When the image has loaded or failed to load, the onStatusChange callback is invoked.

const [state, send] = useMachine(
  avatar.machine({
    onStatusChange(details) {
      // details => { status: "error" | "loaded" }
    },
  }),
)

Styling guide

Earlier, we mentioned that each avatar part has a data-part attribute added to them to select and style them in the DOM.

[data-scope="avatar"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="avatar"][data-part="image"] {
  /* Styles for the image part */
}

[data-scope="avatar"][data-part="fallback"] {
  /* Styles for the fallback part */
}

Creating Component

Create your avatar component by abstracting the machine into your own component.

Usage

import { Avatar } from "./your-avatar"

function Demo() {
  return (
    <Avatar
      src="https://avatars.githubusercontent.com/u/139426"
      name="John Doe"
    />
  )
}

Implementation

Use the the splitProps utility to separate the machine's props from the component's props.

import * as avatar from "@zag-js/avatar"
import { useMachine, normalizeProps } from "@zag-js/react"

export interface AvatarProps extends Omit<avatar.Context, "id"> {
  /**
   * The src of the avatar image
   */
  src?: string
  /**
   * The srcSet of the avatar image
   */
  srcSet?: string
  /**
   * The name of the avatar
   */
  name: string
}

function Avatar(props: AvatarProps) {
  const [machineProps, localProps] = avatar.splitProps(props)

  const [state, send] = useMachine(avatar.machine({ id: useId() }), {
    context: machineProps,
  })

  const api = avatar.connect(state, send, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <span {...api.getFallbackProps()}>{getInitials(localProps.name)}</span>
      <img
        alt="PA"
        src={localProps.src}
        srcSet={localProps.srcSet}
        {...api.getImageProps()}
      />
    </div>
  )
}

function getInitials(name: string) {
  return name
    .split(" ")
    .map((word) => word[0])
    .join("")
}

Methods and Properties

Machine Context

The avatar machine exposes the following context properties:

onStatusChange(details: StatusChangeDetails) => voidFunctional called when the image loading status changes.

idsPartial<{ root: string; image: string; fallback: string; }>The ids of the elements in the avatar. Useful for composition.

idstringThe unique identifier of the machine.

getRootNode() => ShadowRoot | Node | DocumentA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

dir"ltr" | "rtl"The document's text/writing direction.

Machine API

The avatar api exposes the following methods:

loadedbooleanWhether the image is loaded.

setSrc(src: string) => voidFunction to set new src.

setLoaded() => voidFunction to set loaded state.

setError() => voidFunction to set error state.

Data Attributes

Image

data-scope

avatar

data-part

image

data-state

"visible" | "hidden"

Fallback

data-scope

avatar

data-part

fallback

data-state

"hidden" | "visible"

Edit this page on GitHub

Avatar

Anatomy

Usage

Listening for loading status changes

Styling guide

Creating Component

Usage

Implementation

Methods and Properties

Machine Context

Machine API

Data Attributes

On this page