Icon — Icons

17:06

Description

An icon component built on an iconfont font-based icon set, covering icons for most common business scenarios (home, shopping cart, payment, social, directional arrows, etc.), and supporting custom size, color, bold, and vertical fine-tuning.

The component supports two forms, determined automatically by name:

• Font icon: when name is an icon name within the set (e.g. home, star), rendered as a <text> element;
• Image icon: when name is an image URL, rendered as an <image> element (with width / height / imgMode / top).

Examples in this doc are taken verbatim from the component demo page pages/basic/icon (index.uvue / code.uts) — titles map 1:1 to demo blocks and can be copied and run directly.

Compatibility

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

Examples

Size and Color

Customize size via size (in rpx) and color via color (theme color name or any color value), displayed in increasing size; use custom-class to set outer spacing.

View source

<template>
    <view class="icon-row">
        <ux-icon name="home" size="30" color="#2979ff" custom-class="icon-spacing"></ux-icon>
        <ux-icon name="star-fill" size="40" color="#fa3534" custom-class="icon-spacing"></ux-icon>
        <ux-icon name="setting-fill" size="50" color="#19be6b" custom-class="icon-spacing"></ux-icon>
        <ux-icon name="bell-fill" size="60" color="#ff9900" custom-class="icon-spacing"></ux-icon>
    </view>
</template>

<style scoped>
.icon-row {
    display: flex;
    flex-direction: row;
    align-items: center;
    flex-wrap: wrap;
}
.icon-spacing {
    margin-right: 32rpx;
    margin-bottom: 24rpx;
}
</style>

Bold

Control whether the icon is bold via the bold prop, shown side-by-side with a regular icon.

View source

<template>
    <view class="icon-row">
        <ux-icon name="home" bold size="40" color="#2979ff" custom-class="icon-spacing"></ux-icon>
        <ux-icon name="star-fill" size="40" color="#2979ff" custom-class="icon-spacing"></ux-icon>
    </view>
</template>

<style scoped>
.icon-row {
    display: flex;
    flex-direction: row;
    align-items: center;
    flex-wrap: wrap;
}
.icon-spacing {
    margin-right: 32rpx;
    margin-bottom: 24rpx;
}
</style>

Image Icon

Passing an image URL to name renders an image icon; combine with width, height and imgMode to control size and display mode.

View source

<template>
    <view class="icon-row">
        <ux-icon name="/static/logo.png" width="60" height="60" custom-class="icon-spacing"></ux-icon>
        <ux-icon name="/static/logo.png" img-mode="aspectFit" width="60" height="60" custom-class="icon-spacing"></ux-icon>
    </view>
</template>

<style scoped>
.icon-row {
    display: flex;
    flex-direction: row;
    align-items: center;
    flex-wrap: wrap;
}
.icon-spacing {
    margin-right: 32rpx;
    margin-bottom: 24rpx;
}
</style>

Icon List

All icons in the set are listed in a grid; tap any icon to copy its name for use in your project. The demo renders iconList with v-for and writes the tapped name to the clipboard.

View source

<template>
    <view class="icon-grid">
        <view class="icon-item" v-for="(item, index) in iconList" :key="index">
            <ux-icon :name="item.name" size="40" color="#909399"></ux-icon>
            <text class="icon-name">{{ item.name }}</text>
        </view>
    </view>
</template>

<script setup lang="uts">
const iconList = [
    { name: 'home' },
    { name: 'star' },
    { name: 'search' },
    { name: 'setting' },
    { name: 'phone' },
    { name: 'heart' }
];
</script>

<style scoped>
.icon-grid {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.icon-item {
    display: flex;
    flex-direction: column;
    align-items: center;
    width: 33.33%;
    padding: 24rpx 0;
}
.icon-name {
    font-size: 22rpx;
    color: #909399;
    margin-top: 12rpx;
}
</style>

For the full list of icon names, see the complete iconList in the demo page's "Icon List" block (including copying a name to ux-icon), or open the demo page directly.

API

Props

Prop	Description	Type	Default	Version
name	Icon name (see icon set on the demo page); passing an image URL renders an image icon	string	''	-
color	Icon color; accepts a theme color name (e.g. primary) or any color value	string	''	-
size	Font size in rpx; default inherit inherits the parent font size (font-size omitted when unset)	string | number	inherit	-
bold	Whether to show bold	boolean	false	-
top	Vertical offset (rpx, positive downward) for per-icon visual centering fine-tuning	string | number	0	-
index	Index passed back with the click event, to tell which icon was tapped	string | number	''	-
hoverClass	Class applied while touching (define attributes like pressed-scale in it)	string	''	-
customPrefix	Custom font-icon prefix for extending your own icon library	string	uicon	-
imgMode	Image icon mode, see uni-app image component	ImgMode	widthFix	-
width	Image icon width (rpx)	string | number	''	-
height	Image icon height (rpx)	string | number	''	-
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class (for cross-platform root styling; component registered external-class)	string	''	-

Events

Event	Description	Callback Args	Version
click	Triggered when an icon is tapped; index is passed back if non-empty	index: string | number | UniEvent	-
touchstart	Triggered when an icon is touched	index: string | number | UniTouchEvent	-

Slots

ux-icon has no slots — its root element is either a <text> (font icon) or an <image> (image icon).

ux-icon has no slots; the root element itself is the icon.

Notes

1. When name is an icon name within the set, a font icon is rendered; when it's an image URL, an image icon is rendered (in which case size is ignored — use width / height instead).
2. color accepts a theme color name (primary, success, error, warning, info) or any color value; theme names are colored via theme class, other values via inline color.
3. size defaults to inherit; when its value is inherit, the component omits font-size so the icon inherits the parent font size (App does not support the native font-size: inherit).
4. To style the root element (spacing, etc.) use custom-class instead of the page native class; ux-icon registered externalClasses: ['custom-class'], which also lets page classes pierce into the component under Mini Program isolation policy 2.0.
5. A missing icon name in the set renders nothing — verify against the "Icon List" names on the demo page.