Avatar

Displays a user image, initials fallback, or icon.

Introduction

Avatars represent people, accounts, or entities across your interface—in profile menus, comment threads, user lists, and team displays.

When to use: Display a user’s photo, initials, or a recognizable icon whenever identity needs to be shown at a glance.

Compared to similar components:

Badge — A compact label for counts, status text, or tags. Use Badge for standalone indicators like “New” or “3”; use Avatar to show who something belongs to. Compose them together when you need an identity marker with a status label nearby.
Unlike overlay-style badge patterns in other UI libraries, Bridge Badge does not wrap another element—it renders as its own inline label. Position a Badge next to an Avatar when indicating status (e.g. online/offline).

Use the framework selector in the site header to switch between React and Vue.

Import

import { Avatar } from "@bridge-ui/vue/Components/Avatar";

import { Avatar } from "@bridge-ui/react/Components/Avatar";

Basic usage

An Avatar can display an image (src), initials (fallback), or an icon. When no src or fallback is provided, a default user icon is shown.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
import { User } from "@lucide/vue";
</script>

<template>
  <div class="flex flex-wrap items-center gap-4">
    <Avatar fallback="JD" />

    <Avatar :icon="User" color="primary" />

    <Avatar alt="Jane Doe" src="https://i.pravatar.cc/150?img=32" />
  </div>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";
import { User } from "lucide-react";

export default function AvatarBasic() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar fallback="JD" />

      <Avatar icon={User} color="primary" />

      <Avatar alt="Jane Doe" src="https://i.pravatar.cc/150?img=32" />
    </div>
  );
}

Image avatars

Create image avatars by passing src and alt props. The alt text is used for accessibility when the image is displayed.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
</script>

<template>
  <div class="flex flex-wrap items-center gap-4">
    <Avatar alt="Remy Sharp" src="https://i.pravatar.cc/150?img=11" />
    <Avatar alt="Travis Howard" src="https://i.pravatar.cc/150?img=12" />
    <Avatar alt="Cindy Baker" src="https://i.pravatar.cc/150?img=13" />
  </div>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";

export default function AvatarImage() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar alt="Remy Sharp" src="https://i.pravatar.cc/150?img=11" />
      <Avatar alt="Travis Howard" src="https://i.pravatar.cc/150?img=12" />
      <Avatar alt="Cindy Baker" src="https://i.pravatar.cc/150?img=13" />
    </div>
  );
}

Letter avatars

Avatars with simple characters can be created by passing a string to the fallback prop. Combine with color to change the background.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
</script>

<template>
  <div class="flex flex-wrap items-center gap-4">
    <Avatar fallback="H" color="primary" />
    <Avatar fallback="N" color="secondary" />
    <Avatar fallback="OP" color="success" />
  </div>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";

export default function AvatarFallback() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar fallback="H" color="primary" />
      <Avatar fallback="N" color="secondary" />
      <Avatar fallback="OP" color="success" />
    </div>
  );
}

Icon avatars

Icon avatars are created by passing an icon to the icon prop. The icon is shown when no image or fallback text is available.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
import { Folder, User } from "@lucide/vue";
</script>

<template>
  <div class="flex flex-wrap items-center gap-4">
    <Avatar :icon="User" color="primary" />

    <Avatar color="info" :icon="Folder" />
  </div>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";
import { Folder, User } from "lucide-react";

export default function AvatarIcon() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar icon={User} color="primary" />

      <Avatar color="info" icon={Folder} />
    </div>
  );
}

Sizes

Change the avatar size with the size prop. Available sizes: 2xs, xs, sm, md, lg, xl, and 2xl.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
</script>

<template>
  <div class="flex flex-wrap items-end gap-4">
    <Avatar size="2xs" fallback="B" color="primary" />
    <Avatar size="xs" fallback="B" color="primary" />
    <Avatar size="sm" fallback="B" color="primary" />
    <Avatar size="md" fallback="B" color="primary" />
    <Avatar size="lg" fallback="B" color="primary" />
    <Avatar size="xl" fallback="B" color="primary" />
    <Avatar size="2xl" fallback="B" color="primary" />
  </div>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";

export default function AvatarSizes() {
  return (
    <div className="flex flex-wrap items-end gap-4">
      <Avatar size="2xs" fallback="B" color="primary" />
      <Avatar size="xs" fallback="B" color="primary" />
      <Avatar size="sm" fallback="B" color="primary" />
      <Avatar size="md" fallback="B" color="primary" />
      <Avatar size="lg" fallback="B" color="primary" />
      <Avatar size="xl" fallback="B" color="primary" />
      <Avatar size="2xl" fallback="B" color="primary" />
    </div>
  );
}

Rounded

If you need square or rounded avatars, use the rounded prop. The default is full (circular).

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
</script>

<template>
  <div class="flex flex-wrap items-center gap-4">
    <Avatar fallback="N" rounded="none" color="secondary" />
    <Avatar fallback="N" rounded="sm" color="secondary" />
    <Avatar fallback="N" rounded="md" color="secondary" />
    <Avatar fallback="N" rounded="lg" color="secondary" />
    <Avatar fallback="N" rounded="xl" color="secondary" />
    <Avatar fallback="N" rounded="full" color="secondary" />
  </div>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";

export default function AvatarRounded() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar fallback="N" rounded="none" color="secondary" />
      <Avatar fallback="N" rounded="sm" color="secondary" />
      <Avatar fallback="N" rounded="md" color="secondary" />
      <Avatar fallback="N" rounded="lg" color="secondary" />
      <Avatar fallback="N" rounded="xl" color="secondary" />
      <Avatar fallback="N" rounded="full" color="secondary" />
    </div>
  );
}

Fallback slot

When no image is available, you can provide custom fallback content via the fallback slot instead of using the fallback prop.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
</script>

<template>
  <Avatar
    :classes="{
      root: 'ring-2 ring-info-500',
    }"
  >
    <template #fallback>
      <span class="text-xs font-semibold tracking-widest">Slot</span>
    </template>
  </Avatar>
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";

export default function AvatarFallbackSlot() {
  return (
    <Avatar
      classes={{
        root: "ring-2 ring-info-500",
      }}
      slots={{
        fallback: (
          <span className="text-xs font-semibold tracking-widest">Slot</span>
        ),
      }}
    />
  );
}

Customization

Use the classes prop to style individual parts: root, fallback, and image.

<script setup lang="ts">
import { Avatar } from "@bridge-ui/vue/Components/Avatar";
</script>

<template>
  <Avatar
    fallback="JP"
    :classes="{
      root: 'ring-2 ring-info-500',
      fallback: 'font-bold tracking-widest',
    }"
  />
</template>

import { Avatar } from "@bridge-ui/react/Components/Avatar";

export default function AvatarCustomization() {
  return (
    <Avatar
      fallback="JP"
      classes={{
        root: "ring-2 ring-info-500",
        fallback: "font-bold tracking-widest",
      }}
    />
  );
}

Accessibility

Always provide meaningful alt text when displaying an image via src.
When the avatar is decorative and the person’s name appears in adjacent text, you may use an empty alt="" on the image.
Fallback initials and icons are visible content—ensure surrounding text identifies the person so screen reader users have full context.
For icon-only or initials avatars without adjacent labels, provide an accessible name on a wrapping element (e.g. aria-label="Jane Doe").

Anatomy

The Avatar component renders a root <div> that displays one of an image, fallback text, custom slot content, or a default icon:

<div class="avatar-root">
  <!-- one of: -->
  <img class="avatar-image" src="..." alt="Jane Doe" />
  <span class="avatar-fallback">JD</span>
  <!-- or icon -->
</div>

Badge

API

Prop	Type	Default	Description
src	string	—	Image source URL.
alt	string	—	Alt text for the image.
fallback	string	—	Initials shown when no image is available.
icon	IconSource	—	Icon shown when no image or fallback text.
color	AvatarColor	"secondary"	Background color for fallback/icon.
size	AvatarSize	"md"	Avatar dimensions.
rounded	AvatarRounded	"full"	Border radius.
classes	AvatarClasses	—	Classes for root, fallback, image.
slots	AvatarSlots	—	React slot: fallback.