Custom Icons
17:43ux-icon renders the built-in icon set by default. If your project already has its own icon font (for example a ttf exported from an icon platform), you can plug it into ux-icon without touching the library source. The integration takes three steps, all on the application side.
TIP
The library ships no custom font files. The font resource and its codepoint table are maintained by your own project.
Integration Steps
| Step | Where | What to do |
|---|---|---|
| 1 | Project static/ directory | Put the font file there so it is included in the build |
| 2 | Global style in App.uvue | Declare @font-face; its font-family becomes the prefix |
| 3 | onLaunch in App.uvue | Register the codepoint table with $u.registerIconFont(prefix, icons) |
The prefix must be the same string in all three places: the font-family in @font-face, the first argument of registerIconFont, and the custom-prefix value.
Prepare the Font and Codepoint Table
Put the font file in static/, for example static/iconfont.ttf. The CSS exported by the icon platform lists each icon's codepoint:
.custom-icon-sun:before { content: "\e712"; }Take the hex value from content, drop the backslash, and build the codepoint table (icon name as key, hex string as value):
// iconfont.ts
export const customIconFont: JsonObject = {
'sun': 'e712',
'moon': 'e609',
'eye': 'e68e'
}Declare the Font and Register
Declare the font in the global style of App.uvue and register the codepoint table in onLaunch:
<!-- App.uvue -->
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x'
import { customIconFont } from './iconfont.ts'
onLaunch(() => {
$u.registerIconFont('custom-icon', customIconFont)
})
</script>
<style>
@font-face {
font-family: 'custom-icon';
src: url('/static/iconfont.ttf') format('truetype');
font-weight: normal;
font-style: normal;
}
</style>Register before any icon renders; onLaunch is the safest place.
Use in a Page
<template>
<view class="icon-row">
<ux-icon name="sun" size="20" custom-prefix="custom-icon"></ux-icon>
<ux-icon name="eye" size="20" color="#2979ff" custom-prefix="custom-icon"></ux-icon>
</view>
</template>
<style scoped>
.icon-row {
display: flex;
flex-direction: row;
align-items: center;
}
</style>name is a key in the codepoint table. size, color, type, bold and top behave exactly as they do for built-in icons.
List All Icons
The keys of the codepoint table are the icon list, so you can render them all directly:
import { customIconFont } from '@/iconfont.ts'
const customIconList: string[] = JsonObject.keys(customIconFont)<view class="icon-grid">
<view class="icon-item" v-for="(item, index) in customIconList" :key="index">
<ux-icon :name="item" size="20" color="#2979ff" custom-prefix="custom-icon"></ux-icon>
<text class="icon-name">{{ item }}</text>
</view>
</view>How It Works
Font icons are rendered as plain unicode characters rather than relying on the ::before pseudo-element, which App does not support. Once the prefix is registered, the component:
- looks up the codepoint in the registered table;
- inlines the prefix as the node's
font-family, overriding the built-in font class styles (class-style priority is unreliable on App, while an inline style always wins).
You do not need to write icon classes such as .custom-icon-sun, nor maintain font-class styles for your font.
Compatibility
| Platform | Support | Notes |
|---|---|---|
| App | ✅ Supported | The font in static/ is packaged with the app and loaded by the global @font-face |
| H5 | ✅ Supported | url('/static/...') resolves directly; adjust the path when deployed under a sub-path |
| WeChat Mini Program | ✅ Supported | A local font file in static/ renders correctly (verified); if it does not, check the font path and the global style declaration |
Notes
- The font file must live in
static/; files elsewhere are not included in the build. - The
font-familyin@font-face, the prefix passed toregisterIconFont, and thecustom-prefixvalue must be identical; any mismatch renders a blank icon or falls back to the built-in font. uiconis reserved for the built-in icon set. Registering it is ignored with a warning, so pick another prefix.- Re-registering the same prefix replaces the previous table as a whole rather than merging; register the full table again after adding or removing icons.
- An unregistered prefix does not raise an error: the component falls back to the built-in codepoint table and font, so the custom icon name usually renders blank.
- Write codepoints as hex strings (for example
e712), without\u,0x, or&#x;wrappers; a wrong format renders blank. - Icon names must not contain
/or use thedata:base64 form, both of which are treated as image icons. - Custom and built-in icons can be mixed on the same page; omit
custom-prefixfor built-in icons (defaults touicon). - Do not write
::beforeclass styles for icons on App; the component already renders plain unicode.
Troubleshooting
| Symptom | What to check |
|---|---|
| Icon is blank | Prefix identical in all three places; name exists in the table; font is in static/; codepoint format is correct |
| Built-in icon appears | Whether onLaunch ran, the prefix registered, or uicon was used by mistake |
| Icons disappear after build | Whether the font is in static/ and whether the build cleans that file |
| Nothing on WeChat Mini Program | Check that src uses the correct /static/... path and that @font-face is declared in the global style of App.uvue |