Avatar

17:06

Description

An avatar that switches between an image, a text placeholder, and a built-in default. Pass src to show an image, which falls back to the built-in default when empty or on load failure; pass text to show a text avatar using the first character, with bg-color as its background. shape controls circle or square, and size accepts large / default / small or a custom px value. Optionally overlay a gender badge (show-sex) at the top-right and a level icon (show-level) at the bottom-right.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Pass src to show an image avatar, supporting large/default/mini and custom sizes.

View source

<template>
    <view class="avatar-row">
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" @click="onClick" />
        <ux-avatar size="large" src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" />
        <ux-avatar size="small" src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" />
    </view>
</template>

<script setup lang="uts">
const onClick = (index: string | number) => {
    uni.showToast({ title: '点击了头像: ' + index, icon: 'none' });
};
</script>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
    flex-wrap: wrap;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

Text Avatar

Passing text shows the first character as a placeholder, with bg-color for the background.

View source

<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" />
        <ux-avatar text="B" bg-color="#19be6b" size="large" />
        <ux-avatar text="C" bg-color="#fa3534" size="small" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

Shape

shape="circle" is a full circle (default); shape="square" is a square with a 4px small radius. Image and text avatars each compare one tier.

View source

<template>
    <!-- shape 两档全演示：circle 正圆（不传即此档） / square 小圆角 4px 方形 -->
    <view class="avatar-row">
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" shape="circle" />
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" shape="square" custom-class="avatar-item" />
        <ux-avatar text="A" bg-color="#2979ff" shape="circle" size="large" custom-class="avatar-item" />
        <ux-avatar text="B" bg-color="#19be6b" shape="square" size="large" custom-class="avatar-item" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

Gender Badge show-sex

When show-sex=true a gender icon appears at the top-right; man for male, woman for female.

View source

<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" show-sex sex-icon="man" />
        <ux-avatar text="B" bg-color="#fa3534" show-sex sex-icon="woman" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

Level Icon show-level

When show-level=true a level icon appears at the bottom-right, with a customizable background.

View source

<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" show-level />
        <ux-avatar text="B" bg-color="#fa3534" show-level level-bg-color="#ff9900" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

Custom Badge Color

Customize the badge background via sex-bg-color / level-bg-color.

View source

<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" show-sex sex-icon="man" sex-bg-color="#19be6b" />
        <ux-avatar text="B" bg-color="#fa3534" show-level level-bg-color="#2979ff" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

Image Mode img-mode

Set the image crop mode via img-mode: aspectFill keeps aspect ratio, scaleToFill stretches to fill.

View source

<template>
    <view class="avatar-row">
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" img-mode="aspectFill" />
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" img-mode="scaleToFill" size="large" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
bgColor	Background color (mainly for text avatars)	string	'transparent'	-
src	Avatar image path; falls back to the built-in default avatar on load failure	string	''	-
size	Size: large / default / small, or a number in px (width equals height)	string | number	'default'	-
shape	Avatar shape (see Shape in types/global.uts): square — 4px small-radius square, circle — full circle; renamed from mode	'square' | 'circle'	'circle'	-
text	Text content (only the first character is shown)	string	''	-
imgMode	Image crop mode	ImgMode	'aspectFill'	-
index	Identifier (returned with the click event)	string | number	''	-
sexIcon	Gender badge at the top-right: man / woman	string	'man'	-
levelIcon	Level icon at the bottom-right	string	'level'	-
levelBgColor	Background color of the level icon	string	''	-
sexBgColor	Background color of the gender badge	string	''	-
showSex	Whether to show the gender badge	boolean	false	-
showLevel	Whether to show the level icon	boolean	false	-

Events

Event	Description	Params	Version
click	Emitted when the avatar is clicked	index: string | number	-

Slots

Slot	Description	Version
default	Custom avatar content, used as a fallback when neither src nor text is provided	-

Notes

1. An empty src or an image that fails to load (@error) falls back to the component's built-in base64 default avatar; therefore the component still renders that default even without src / text, and the default slot (the no-image no-text fallback) normally never shows.
2. text only uses its first character for the text avatar; the font size scales with size (about 0.4x, clamped to 10–28px).
3. The text avatar's color is fixed to white (theme $u-white-color); set the background via bg-color, which defaults to transparent (no background when omitted).
4. size presets: large=60 / default=45 / small=30 (px); a numeric value is treated as px with equal width and height.
5. shape was renamed from mode: circle is a full circle and square a 4px small-radius square. Custom radius via custom-style only affects text/background avatars — an image avatar's radius lives on the inner imgStyle and cannot be overridden from the outside.
6. The gender/level badges are absolutely positioned at right: -7%, protruding beyond the avatar, and rely on the root's overflow: visible (already declared). show-sex defaults to sex-icon="man" (primary theme color); woman uses the error color and none the warning color. show-level defaults to the warning color, overridable via level-bg-color.
7. img-mode matches uni's image mode and defaults to aspectFill; if the result is not what you need, try widthFix.