Avatars

Avatars are visual representations of users that can display profile pictures, initials, or fallback icons. They support various sizes, shapes, and status indicators for rich user interfaces.

Basic Usage

Avatars come in different sizes and shapes to suit various design needs. Choose between circular (default), rounded, or square shapes.

Avatar Sizes and Shapes

100%

<div class="flex items-center gap-4">
    <byte-avatar
      src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
      size="sm">
    </byte-avatar>

    <byte-avatar
      src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
      size="md"
      shape="rounded">
    </byte-avatar>

    <byte-avatar
      src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
      size="lg"
      shape="square">
    </byte-avatar>
  </div>

Fallback Display

When an image fails to load or isn't provided, avatars can display initials or a default user icon. This ensures a consistent look even when images are unavailable.

Avatar Fallbacks

100%

<div class="flex items-center gap-4">
    <byte-avatar
      fallback="AF"
      size="md">
    </byte-avatar>

    <byte-avatar
      fallback="JD"
      size="md"
      shape="rounded">
    </byte-avatar>

    <byte-avatar
      size="md"
      shape="square">
    </byte-avatar>
  </div>

Status Indicators

Add status indicators to show user presence states like online, offline, busy, or away. Status indicators automatically position themselves based on the avatar's shape.

Avatars with Status

100%

<div class="flex items-center gap-4">
    <byte-avatar
      src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
      size="lg"
      status="online">
    </byte-avatar>

    <byte-avatar
      src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
      size="lg"
      status="busy">
    </byte-avatar>

    <byte-avatar
      fallback="AF"
      size="lg"
      status="away">
    </byte-avatar>

    <byte-avatar
      src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
      size="lg"
      status="offline">
    </byte-avatar>
  </div>

Avatar Groups

Stack multiple avatars together to represent groups or teams. Use the fallback option to show the number of additional users.

Grouped Avatars

100%

<div class="flex -space-x-2">
    <byte-avatar src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg" size="sm"></byte-avatar>
    <byte-avatar src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg" size="sm"></byte-avatar>
    <byte-avatar fallback="+3" size="sm"></byte-avatar>
  </div>

API Reference

Properties

Property

Type

Default

Description

src

string

URL of the avatar image

size

string

'md'

Size of the avatar: 'xs', 'sm', 'md', 'lg', 'xl'

shape

string

'circle'

Shape of the avatar: 'circle', 'rounded', 'square'

fallback

string

Text to display when image fails to load

status

string

User status: 'online', 'offline', 'busy', 'away'

Size Reference

Size

Dimensions

Use Case

24px

Compact lists, tight spaces

32px

Comments, small components

40px

Default size, general use

48px

Profile pages, headers

56px

Large profiles, hero sections

Best Practices

Use appropriate sizes for different contexts
Provide meaningful fallback text (usually user initials)
Keep status indicators up to date
Use consistent shapes within the same context
Optimize avatar images for performance

Interactive Tour Example

Adding a Tour to Your UI

100%

<div id="tour-demo-container">
        <byte-avatar
          id="demo-avatar"
          src="https://byteui.dev/assets/andrea-fomera-8411cac6.jpg"
          size="lg"
          status="online">
        </byte-avatar>

        <byte-tour-step
          target="#demo-avatar"
          title="Welcome to Byte!"
          content="This is an example of a tour step. You can use this to guide users through your application.">
        </byte-tour-step>
      </div>

Try it yourself:

Start Tour

Pro tip: When using avatars in a list or grid, consider preloading images to prevent layout shifts.