Avatar

LhAvatar is used to display user avatars. Supports image, icon, and text modes with automatic fallback.

Basic Usage

Image Avatar

<script setup lang="ts">
import { LhAvatar } from '@lh-ui/vue3'
</script>

<template>
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
</template>

<script>
import { LhAvatar } from '@lh-ui/vue3'

export default {
  components: { LhAvatar },
}
</script>

<template>
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
</template>

fit sets the crop mode (native object-fit) and alt provides alternative text.

Fit & alt

<script setup lang="ts">
</script>

<template>
  <!-- Fit & alt -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="User avatar"
  />
</template>

<script>
export default {}
</script>

<template>
  <!-- Fit & alt -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="User avatar"
  />
</template>

Shape & Size

Circle & Square, Four Sizes

SMLC

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar shape="square" size="small" text="S" />
    <LhAvatar shape="square" size="medium" text="M" />
    <LhAvatar shape="square" size="large" text="L" />
    <LhAvatar size="large" text="Circle" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar shape="square" size="small" text="S" />
    <LhAvatar shape="square" size="medium" text="M" />
    <LhAvatar shape="square" size="large" text="L" />
    <LhAvatar size="large" text="Circle" />
  </div>
</template>

Text & Icon Fallback

Fallback to icon or text when no image

HA

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="Hello" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="Hello" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

Text avatars automatically show the first character (first Chinese character, or first letter capitalized for English).

Image Load Error

Fallback to text on error and trigger error event

<script setup lang="ts">
function onError(e: Event) {
  console.log('avatar load error', e)
}
</script>

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="F"
    @error="onError"
  />
</template>

<script>
export default {
  methods: {
    onError(e) {
      console.log('avatar load error', e)
    },
  },
}
</script>

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="F"
    @error="onError"
  />
</template>

Props

Prop	Description	Type	Default
src	Image URL, fallback to icon/text when empty	string	—
alt	Alt text	string	—
icon	Icon name (a built-in LhIcon name, shown when src is missing)	LhIconName	—
text	Text content (first char shown when src and icon missing)	string	—
shape	Shape	"circle" | "square"	'circle'
size	Size	"small" | "medium" | "large" | "mini" | "x-large"	'medium'
fit	Image fill mode	"fill" | "contain" | "cover" | "none" | "scale-down"	'cover'
sx	Shorthand layout props (e.g. { mt: 2, w: '50%' }), applied as inline styles on the root element	LhSxProps	—

Events

Event	Description	Callback
error	Image load failed	(e: Event) => void

Accessibility

• Image mode relies on the <img alt> attribute; when alt is omitted it falls back to text, then to avatar
• Icon and text modes carry role="img" on the root element, using alt as the accessible name when provided; the icon itself is aria-hidden

Type Definitions

The TypeScript type structures exported by this component (auto-extracted from packages/components/avatar/src/types.ts and @lh-ui/share/core/* sources; click each entry to expand; see the Props table above for attribute descriptions):

LhAvatarProps

export interface LhAvatarProps {

  src?: string

  alt?: string

  icon?: LhIconName

  text?: string

  shape?: LhAvatarComponentShape

  size?: LhAvatarSize

  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'

  sx?: LhSxProps
}

LhAvatarSize

export type LhAvatarSize = LhComponentSize

LhAvatarShape

export type LhAvatarShape = LhAvatarComponentShape

LhAvatarComponentShape _{(from @lh-ui/share/core/avatar)}

export type LhAvatarShape = 'circle' | 'square'

LhIconName _{(from @lh-ui/share/core/icon (svgs.ts))}

export type LhIconName = keyof typeof LH_ICON_SVGS_CONST

LhComponentSize _{(from @lh-ui/share/core/shared)}

export type LhComponentSize = (typeof LH_SIZE_CONST)[keyof typeof LH_SIZE_CONST]