Avatar

Neo-brutalist avatar component for displaying user profile images with fallback support. Includes Avatar, AvatarImage, and AvatarFallback sub-components, supporting multiple variants, sizes, shapes, and status indicators.

Demo

Preview

尺寸

小默认大特大

形状

方形圆角

带图片

用户用户

变体

默主次强

状态

在在线离离线忙忙碌无

工牌吊孔（lanyard）

工班在线

Installation

pnpm dlx brutx-vue@latest add avatar

Usage

<script setup>
import { Avatar, AvatarImage, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <Avatar size="default" shape="square">
        <AvatarImage src="/avatar.jpg" alt="User avatar" />
        <AvatarFallback>JD</AvatarFallback>
    </Avatar>
</template>

Fallback Behavior

When the image fails to load, AvatarFallback is automatically displayed:

<script setup>
import { Avatar, AvatarImage, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <Avatar>
        <AvatarImage src="/broken-url.jpg" alt="User" />
        <AvatarFallback>JD</AvatarFallback>
    </Avatar>
</template>

Status Indicator

Renders a small status dot at the bottom-right corner of the avatar (w-3 h-3 rounded-full border-3 border-brutal-bg). Not rendered when status="none" (default).

Status	Color	Description
online	bg-brutal-success	Online (green)
offline	bg-brutal-muted	Offline (gray)
busy	bg-brutal-destructive	Busy (red)
none	—	Not rendered (default)

<script setup>
import { Avatar, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex items-center gap-4">
        <Avatar size="lg" status="online">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" status="offline">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" status="busy">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
    </div>
</template>

Variants

Controls the background color of the avatar root container and AvatarFallback, passed down to sub-components via provide/inject.

Variant	Root Container Background	Fallback Background
default	bg-brutal-muted/20	bg-brutal-muted
primary	bg-brutal-primary/20	bg-brutal-primary
secondary	bg-brutal-secondary/20	bg-brutal-secondary
accent	bg-brutal-accent/20	bg-brutal-accent

<script setup>
import { Avatar, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex items-center gap-4">
        <Avatar size="lg" variant="default">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" variant="primary">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" variant="secondary">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" variant="accent">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
    </div>
</template>

Sizes

Size	Dimensions
sm	h-8 w-8 (32px)
default	h-10 w-10 (40px)
lg	h-14 w-14 (56px)
xl	h-20 w-20 (80px)

Shapes

Shape	Description
square	No border radius (default)
rounded	Uses the --brutal-radius token

<script setup>
import { Avatar, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <Avatar size="lg" shape="rounded">
        <AvatarFallback>JD</AvatarFallback>
    </Avatar>
</template>

Sub-components

Component	Description
Avatar	Root container providing size, shape, variant, and status context
AvatarImage	Avatar image that automatically hides on load failure
AvatarFallback	Fallback content that automatically shows when the image is not visible

API Reference

Avatar

Avatar — Props

Name	Type	Default	Description
variant	"accent" | "default" | "primary" | "secondary" | undefined	"default"	Sets the color variant used by the avatar fallback content.
Details Declared type NonNullable<"default" | "primary" | "secondary" | "accent" | null | undefined> | undefined Literal values "accent" "default" "primary" "secondary" Default value details Declaration 'default' Source: packages/ui/src/components/avatar/Avatar.vue Resolved value "default" Source Avatar.vue:15 packages/ui/src/components/avatar/Avatar.vue
size	"default" | "lg" | "sm" | "xl" | undefined	"default"	Sets the size of the avatar container and its content.
Details Declared type NonNullable<"default" | "lg" | "sm" | "xl" | null | undefined> | undefined Literal values "default" "lg" "sm" "xl" Default value details Declaration 'default' Source: packages/ui/src/components/avatar/Avatar.vue Resolved value "default" Source Avatar.vue:16 packages/ui/src/components/avatar/Avatar.vue
shape	"rounded" | "square" | undefined	"square"	Sets the avatar container to a square or rounded shape.
Details Declared type NonNullable<"square" | "rounded" | null | undefined> | undefined Literal values "rounded" "square" Default value details Declaration 'square' Source: packages/ui/src/components/avatar/Avatar.vue Resolved value "square" Source Avatar.vue:17 packages/ui/src/components/avatar/Avatar.vue
status	AvatarStatus | undefined	"none"	Sets the status indicator at the avatar’s lower-right corner; none hides the indicator.
Details Declared type AvatarStatus | undefined Literal values "busy" "none" "offline" "online" Referenced types AvatarStatus Type definition — AvatarStatus type AvatarStatus = 'online' | 'offline' | 'busy' | 'none' Default value details Declaration 'none' Source: packages/ui/src/components/avatar/Avatar.vue Resolved value "none" Source Avatar.vue:18 packages/ui/src/components/avatar/Avatar.vue
lanyard	boolean | undefined	false	Shows a decorative lanyard grommet at the top; the decoration is hidden from the accessibility tree.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/avatar/Avatar.vue Resolved value false Source Avatar.vue:20 packages/ui/src/components/avatar/Avatar.vue
class	string | undefined	undefined	CSS classes added to the avatar root container.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/avatar/Avatar.vue Resolved value undefined Source Avatar.vue:21 packages/ui/src/components/avatar/Avatar.vue

Avatar — Slots

Name	Signature or type	Description
#default	{}	Composes the AvatarImage and AvatarFallback subcomponents.
Details Declared type {} Source Avatar.vue packages/ui/src/components/avatar/Avatar.vue

AvatarFallback

AvatarFallback — Props

Name	Type	Default	Description
delayMs	number | undefined	undefined	Sets the delay before fallback content appears while the image is loading or unavailable; it appears immediately when omitted.
Details Declared type number | undefined Default value details Declaration undefined Source: packages/ui/src/components/avatar/AvatarFallback.vue Resolved value undefined Source AvatarFallback.vue:10 packages/ui/src/components/avatar/AvatarFallback.vue
class	string | undefined	undefined	CSS classes added to the fallback content root.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/avatar/AvatarFallback.vue Resolved value undefined Source AvatarFallback.vue:11 packages/ui/src/components/avatar/AvatarFallback.vue
asChild	boolean | undefined	undefined	Merges the root element’s semantics and attributes into the single default-slot child; when enabled, as is ignored.
Details Declared type boolean | undefined Literal values false true Default value details Declaration undefined Source: packages/ui/src/components/avatar/AvatarFallback.vue Resolved value undefined Source AvatarFallback.vue packages/ui/src/components/avatar/AvatarFallback.vue
as	AsTag | Component | undefined	"span"	Specifies the HTML tag or Vue component rendered as the root; asChild takes precedence.
Details Declared type AsTag | Component | undefined Literal values "a" "button" "div" "form" "h2" "h3" "img" "input" "label" "li" "nav" "ol" "p" "span" "svg" "template" "ul" Default value details Declaration 'span' Source: packages/ui/src/components/avatar/AvatarFallback.vue Resolved value "span" Source AvatarFallback.vue packages/ui/src/components/avatar/AvatarFallback.vue

AvatarFallback — Slots

Name	Signature or type	Description
#default	{}	Text, an icon, or other fallback content shown when the image is unavailable.
Details Declared type {} Source AvatarFallback.vue packages/ui/src/components/avatar/AvatarFallback.vue

AvatarImage

AvatarImage — Props

Name	Type	Default	Description
src	string | undefined	undefined	The URL of the avatar image.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/avatar/AvatarImage.vue Resolved value undefined Source AvatarImage.vue:7 packages/ui/src/components/avatar/AvatarImage.vue
alt	string | undefined	""	Alternative text for the image; the default empty string treats it as decorative content.
Details Declared type string | undefined Default value details Declaration '' Source: packages/ui/src/components/avatar/AvatarImage.vue Resolved value "" Source AvatarImage.vue:8 packages/ui/src/components/avatar/AvatarImage.vue
class	string | undefined	undefined	CSS classes added to the avatar image element.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/avatar/AvatarImage.vue Resolved value undefined Source AvatarImage.vue:9 packages/ui/src/components/avatar/AvatarImage.vue

Accessibility

• ARIA Attributes: The status dot uses role="status" (a live region) with an inner sr-only text carrying the status label; label changes on status or language switches are announced by screen readers
• Internationalization: Status labels provide localized text via i18n:
  • online -> "Online"
  • offline -> "Offline"
  • busy -> "Busy"