# Custom Font List

- Human documentation: [https://docs.univer.ai/guides/docs/ui/fonts](https://docs.univer.ai/guides/docs/ui/fonts)

- Agent Markdown: [https://docs.univer.ai/guides/docs/ui/fonts.md](https://docs.univer.ai/guides/docs/ui/fonts.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [docs/ui/fonts.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/ui/fonts.mdx)

---

## Font Structure Definition

In Univer, fonts are defined using the `IFontConfig` interface:

| Property   | Type                                                                   | Description                                                                                                                                             |
| ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`    | `string`                                                               | The unique identifier of the font, usually the preferred value for CSS font-family.                                                                     |
| `label`    | `string`                                                               | The translation key for internationalization. If this key is not specified when the Univer instance is created, the passed value is displayed directly. |
| `category` | `'sans-serif' \| 'serif' \| 'monospace' \| 'display' \| 'handwriting'` | Font category, used for UI grouping (optional).                                                                                                         |

> [!NOTE]
> Univer does not prevent users from selecting uninstalled fonts. If a font is not installed on the client, the browser will substitute it with the default font.

## Using Custom Fonts

You can define the options in the font dropdown menu by configuring the `customFontFamily` parameter of `UniverUIPlugin`.

```typescript
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
  customFontFamily: {
    list: [
      {
        value: 'PingFang SC',
        label: '苹方（简）',
        category: 'sans-serif',
      },
      {
        value: 'Helvetica Neue',
        label: 'Helvetica Neue',
        category: 'sans-serif',
      },
    ],
    // Whether to override the default font list, defaults to false
    override: true,
  },
})
```

### Facade API

In addition to configuration during initialization, you can also dynamically register new fonts at runtime via the Facade API. This is very useful in scenarios where font resources need to be loaded asynchronously.

```typescript
univerAPI.addFonts([{
  value: 'PingFang SC',
  label: 'PingFang SC',
  category: 'sans-serif',
}, {
  value: 'Helvetica Neue',
  label: 'Helvetica Neue',
  category: 'sans-serif',
}])
```