n-avatar

Avatar component for displaying user profile images, icons, or text. Invoke when user needs to implement user avatars, avatar groups, or customize avatar appearance in Naive UI.

SKILL.md

GitHub

Naive UI Avatar Component

Avatar component for displaying user profile images, icons, or text with various sizes and shapes.

When to Use

Use this component when:

  • User profiles: Display user avatar images in navigation bars, comment sections, or user cards
  • Team displays: Show multiple user avatars in a group layout
  • Icon placeholders: Use icons or text as avatar placeholders when images are unavailable
  • Notification badges: Combine with badge component to show notification counts

When to Invoke

Invoke this skill when:

  • User needs to implement user avatar display
  • User wants to create avatar groups with overflow handling
  • User needs lazy loading for avatar images
  • User wants to customize avatar size, shape, or color
  • User needs fallback images when avatar fails to load
  • User asks about avatar with icons or text content

Features

  • Multiple Sizes: small, medium, large, or custom pixel size
  • Shape Options: square or round (circular)
  • Image Support: src for image URL, fallback-src for error handling
  • Lazy Loading: Load images only when entering viewport
  • Avatar Groups: Display multiple avatars with max count and overflow
  • Icon/Text Support: Use icons or text as avatar content
  • Custom Colors: Custom background and text colors
  • Object Fit: Control how images fit within the avatar

API Reference

Avatar Props

Name Type Default Description
bordered boolean false Whether to display a avatar with border.
color string undefined The background color of the avatar.
fallback-src string undefined Image URL to show when avatar fails to load.
img-props ImgHTMLAttributes undefined The props of the img element inside the component.
intersection-observer-options { root?: Element | Document | string | null, rootMargin?: string, threshold?: number | number[] } undefined Intersection observer's config to be applied when lazy=true.
lazy boolean false Load image after it enters viewport.
object-fit 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' 'fill' Object-fit type of the image in the container.
render-fallback () => VNodeChild undefined Render function of fallback content.
render-placeholder () => VNodeChild undefined Render function of placeholder.
round boolean false Whether to display a rounded avatar.
size 'small' | 'medium' | 'large' | number 'medium' Avatar's size.
src string undefined Avatar's image source.
on-error (e: Event) => void undefined Callback executed when the avatar image fails to load.

AvatarGroup Props

Name Type Default Description
expand-on-hover boolean false Expand on hover.
max number undefined Max avatar count in the group.
max-style Object | string undefined The style of the overflow placeholder.
options Array<AvatarGroupOption> [] Avatar group options.
size 'small' | 'medium' | 'large' | number 'medium' Avatar's size.
vertical boolean false Whether display a vertical avatar group.

Avatar Slots

Name Parameters Description
default () The content of the avatar.
fallback () Content if avatar load fails.
placeholder () Placeholder shown when image is not loaded.

AvatarGroup Slots

Name Parameters Description
avatar (info: { option: { src: string } }) Avatar of the avatar group.
default () The content of the avatar group.
rest (info: { options: Array<{ src: string }>, rest: number }) Overflow indicator of the avatar group.

Basic Usage

Basic Sizes

<template>
  <n-space align="flex-end">
    <n-avatar
      size="small"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
    <n-avatar
      size="medium"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
    <n-avatar
      size="large"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
    <n-avatar
      :size="48"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
  </n-space>
</template>

Round Avatars

<template>
  <n-space align="flex-end">
    <n-avatar
      round
      size="small"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
    <n-avatar
      round
      size="medium"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
    <n-avatar
      round
      size="large"
      src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
    />
  </n-space>
</template>

Custom Color

<template>
  <n-avatar
    :style="{
      color: 'yellow',
      backgroundColor: 'red',
    }"
  >
    M
  </n-avatar>
</template>

With Badge

<template>
  <n-badge value="999+">
    <n-avatar>App</n-avatar>
  </n-badge>
</template>

With Icon

<template>
  <n-avatar>
    <n-icon>
      <MdCash />
    </n-icon>
  </n-avatar>
</template>

Fallback Image

<template>
  <n-avatar
    round
    size="small"
    src="empty.png"
    fallback-src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
  />
</template>

Lazy Loading

<template>
  <n-avatar
    lazy
    src="https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg"
  />
</template>

Common Patterns

Avatar Group

<template>
  <n-avatar-group :options="options" :size="40" :max="3">
    <template #avatar="{ option: { name, src } }">
      <n-tooltip>
        <template #trigger>
          <n-avatar :src="src" />
        </template>
        {{ name }}
      </n-tooltip>
    </template>
  </n-avatar-group>
</template>

<script setup>
import { ref } from 'vue'

const options = ref([
  { name: 'User 1', src: 'https://example.com/avatar1.jpg' },
  { name: 'User 2', src: 'https://example.com/avatar2.jpg' },
  { name: 'User 3', src: 'https://example.com/avatar3.jpg' },
  { name: 'User 4', src: 'https://example.com/avatar4.jpg' },
])
</script>

Avatar with Error Handling

<template>
  <n-avatar
    :src="avatarUrl"
    :fallback-src="defaultAvatar"
    @error="handleError"
  >
    <template #fallback>
      <n-icon><UserIcon /></n-icon>
    </template>
  </n-avatar>
</template>

<script setup>
import { ref } from 'vue'

const avatarUrl = ref('https://example.com/user-avatar.jpg')
const defaultAvatar = ref('https://example.com/default-avatar.jpg')

const handleError = (e) => {
  console.error('Avatar failed to load:', e)
}
</script>

User Card with Avatar

<template>
  <n-card>
    <n-space align="center">
      <n-avatar
        round
        :size="64"
        :src="user.avatar"
      />
      <div>
        <n-text strong>{{ user.name }}</n-text>
        <n-text depth="3">{{ user.email }}</n-text>
      </div>
    </n-space>
  </n-card>
</template>

<script setup>
import { ref } from 'vue'

const user = ref({
  name: 'John Doe',
  email: 'john@example.com',
  avatar: 'https://example.com/avatar.jpg'
})
</script>

Lazy Loading with Intersection Observer

<template>
  <div id="scroll-container" style="overflow: auto; height: 200px;">
    <n-space vertical>
      <n-avatar
        v-for="src in avatarList"
        :key="src"
        size="small"
        lazy
        :src="src"
        :intersection-observer-options="{
          root: '#scroll-container',
        }"
      />
    </n-space>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const avatarList = ref([
  'https://example.com/avatar1.jpg',
  'https://example.com/avatar2.jpg',
])
</script>

Best Practices

  1. Use fallback images: Always provide a fallback-src for better user experience

    <n-avatar
      :src="userAvatar"
      fallback-src="/default-avatar.png"
    />
    
  2. Use round avatars for user profiles: Circular avatars are more common for user representation

    <n-avatar round :src="user.avatar" />
    
  3. Lazy load avatars in lists: Use lazy loading for avatar lists to improve performance

    <n-avatar lazy :src="avatar" />
    
  4. Use appropriate sizes: Match avatar size with context

    • Small for inline text or compact lists
    • Medium for comments or cards
    • Large for profile pages or headers
  5. Combine with Badge for notifications: Show notification counts on avatars

    <n-badge :value="unreadCount" :show="unreadCount > 0">
      <n-avatar :src="user.avatar" />
    </n-badge>
    
  6. Use object-fit for image cropping: Control how images fit within avatar

    <n-avatar object-fit="cover" :src="user.avatar" />
    
  7. Avatar groups for teams: Use n-avatar-group for displaying multiple users

    <n-avatar-group :options="teamMembers" :max="5" />