Skip to content

Custom Icons ​

17:43

ux-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 ​

StepWhereWhat to do
1Project static/ directoryPut the font file there so it is included in the build
2Global style in App.uvueDeclare @font-face; its font-family becomes the prefix
3onLaunch in App.uvueRegister 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:

css
.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):

ts
// 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:

vue
<!-- 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 ​

vue
<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:

ts
import { customIconFont } from '@/iconfont.ts'

const customIconList: string[] = JsonObject.keys(customIconFont)
vue
<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:

  1. looks up the codepoint in the registered table;
  2. 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 ​

PlatformSupportNotes
App✅ SupportedThe font in static/ is packaged with the app and loaded by the global @font-face
H5✅ Supportedurl('/static/...') resolves directly; adjust the path when deployed under a sub-path
WeChat Mini Program✅ SupportedA local font file in static/ renders correctly (verified); if it does not, check the font path and the global style declaration

Notes ​

  1. The font file must live in static/; files elsewhere are not included in the build.
  2. The font-family in @font-face, the prefix passed to registerIconFont, and the custom-prefix value must be identical; any mismatch renders a blank icon or falls back to the built-in font.
  3. uicon is reserved for the built-in icon set. Registering it is ignored with a warning, so pick another prefix.
  4. 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.
  5. 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.
  6. Write codepoints as hex strings (for example e712), without \u, 0x, or &#x; wrappers; a wrong format renders blank.
  7. Icon names must not contain / or use the data: base64 form, both of which are treated as image icons.
  8. Custom and built-in icons can be mixed on the same page; omit custom-prefix for built-in icons (defaults to uicon).
  9. Do not write ::before class styles for icons on App; the component already renders plain unicode.

Troubleshooting ​

SymptomWhat to check
Icon is blankPrefix identical in all three places; name exists in the table; font is in static/; codepoint format is correct
Built-in icon appearsWhether onLaunch ran, the prefix registered, or uicon was used by mistake
Icons disappear after buildWhether the font is in static/ and whether the build cleans that file
Nothing on WeChat Mini ProgramCheck that src uses the correct /static/... path and that @font-face is declared in the global style of App.uvue

Next Steps ​