@univerjs/icons-vue

@univerjs/icons

@univerjs/icons is a set of icons designed for office software scenarios., it contains a series of icons and React components, you can use them in your React project.

Installation

# npm
npm install @univerjs/icons

# pnpm
pnpm add @univerjs/icons

# yarn
yarn add @univerjs/icons

For Vue 3 projects, install the Vue package:

# npm
npm install @univerjs/icons-vue

# pnpm
pnpm add @univerjs/icons-vue

# yarn
yarn add @univerjs/icons-vue

Usage

Use icons just like render a React component:

import { ShapePieIcon } from '@univerjs/icons'

function App() {
  return <ShapePieIcon />
}

Because icons are React components, you can pass standard SVG attributes to them, such as style:

function App() {
  return <ShapePieIcon preserveStrokeWidth style={{ color: '#3526de', fontSize: '48px' }} />
}

<SmileIcon style={{ color: '#3526de', fontSize: '48px' }} />

Standard usage

Instead of adding various props to the icons, we prefer to follow the existing behaviors on the web. This way, we can leverage solutions that people are familiar with and have already been tested.

• All icons have a height and width of 1em, so you can adjust the size of the icon by adjusting the fontSize.
• All monochrome icons can be adjusted in overall color using the color prop.
• Stroke-based icons can preserve the line width they render at 16 × 16 by setting preserveStrokeWidth; that width stays fixed at every later size. The icon catalogue marks icons whose visible SVG strokes fully support this behavior. Filled artwork is unaffected and does not prevent an otherwise compatible icon from being marked as supported.

Additionally: We also provide some multi-colored icons, which have fixed colors.

<Loading style={{ fontSize: '48px' }} />

For some complex situations, such as adjusting the color of specific parts of an icon, we have added a color channel as a parameter for the component. Similar to monochrome icons, this requires prior communication with the designer to determine which parts should be controlled locally.

function App() {
  return (
    <>
      <PaintBucket style={{ fontSize: '48px' }} extend={{ colorChannel1: 'red' }} />
      <PaintBucket style={{ fontSize: '48px' }} extend={{ colorChannel1: 'blue' }} />
    </>
  )
}

Vue 3 Usage

Use icons as Vue components:

<script setup lang="ts">
import { ShapePieIcon } from '@univerjs/icons-vue'
</script>

<template>
  <ShapePieIcon preserve-stroke-width class="toolbar-icon" style="font-size: 48px" />
</template>

Vue icons follow the same sizing and color conventions:

<script setup lang="ts">
import { PaintBucketDoubleIcon, SmileDoubleIcon } from '@univerjs/icons-vue'
</script>

<template>
  <SmileDoubleIcon style="color: #3526de; font-size: 48px" />
  <PaintBucketDoubleIcon style="font-size: 48px" :extend="{ colorChannel1: 'red' }" />
</template>

Icon source file

The icon resources provided by the designer are placed in packages/svg/{single,double,other}. They are organized into different subdirectories to distinguish their categories.

Please note that the names of the source files should be in kebab case, which means all lowercase with hyphens separating words.

Icon optimization and component generation

Run pnpm build to refresh the source manifest, validate stroke capabilities, and generate the React and Vue packages through the Node.js and SVGO pipeline.

Optimizing SVG size: The SVG files submitted by designers are usually generated by editors such as Figma or Sketch, and they often contain a lot of unnecessary attributes (such as id) and non-optimized element properties. Rendering such SVG files directly would result in larger file sizes for icons. Therefore, we use SVGO to optimize the content of SVG files, reducing their size while maintaining rendering quality.

Standardizing icon properties: The original SVGs generally have dimensions that match the designer's canvas size, making them unsuitable for different usage scenarios with varying sizes. Additionally, colors are typically predetermined by designers and cannot be changed arbitrarily. In this step, we standardize attributes within SVG tags, such as width, height, strokeColor, etc.

Generating icon components: Finally, we generate corresponding React and Vue components for each SVG source file. Edit the SVG sources rather than generated component files.

Design and visual verification

Use pnpm dev to open the source catalogue. The catalogue starts at the 16 px toolbar size. Compare families shows related icons at 16, 20, 24, and 32 px on light and dark backgrounds, independently of the catalogue search, size, and color controls. The Preserve stroke width switch applies to both views.

For common outline toolbar icons:

• Use a 16 × 16 viewBox and a 1.2 px baseline stroke. Keep strokes as SVG strokes so preserveStrokeWidth can control them.
• Reuse the same underlying geometry within a family, such as the Search/Zoom lens and handle. Check optical size and centering together, including mirrored and diagonal variants.
• Use round line caps and joins. Common rectangular containers use a 1.2 px corner radius; small tiles use 0.6 px.
• Reduce detail that merges at 16 px. Leave visible gaps between chart sectors and mathematical elements. Mathematical rules may use 1 px strokes alongside serif notation.
• Preserve intentional differences in filled status icons, brands, mathematical notation, and drawing shapes. Do not convert semantic fills or drawing presets into generic outlines.

Before submitting an icon change, compare its family at all four sizes and on both backgrounds with stroke preservation on and off. Check clipping, legibility, balance, and unchanged meaning. With stroke preservation enabled, change families and search filters, then reset to verify stroke widths restore correctly. Run pnpm build, pnpm --filter ./packages/app test, and pnpm --filter ./packages/app typecheck; the PR workflow also builds the catalogue. These rules guide the common toolbar family rollout, not a claim that every existing icon already follows them.

Interface definition of icon components

type IconProps = React.SVGAttributes<SVGSVGElement> & {
  /**
   * Preserve the stroke width rendered at 16 × 16 as the icon scales.
   */
  preserveStrokeWidth?: boolean
  /**
   * The color of the icon.
   */
  color?: string
  /**
   * The extend color of the icon.
   */
  extend?: {
    colorChannel1?: string
  }
}

FAQ

Why not use SVG sprite / iconfont / base64 + css background-img and other technical solutions?

React component solution has outstanding advantages in the following two aspects:

On-demand usage. Some technical solutions, including SVG sprite and iconfont, will cause icons to be used on demand. This means that the icons packaged into the final resources are not actually used by you, but all the icons provided by the icon library. Although it is possible to generate a sprite or iconfont containing only the icons you use through some technical means, this process is quite cumbersome. In comparison, @univerjs/icons is a tree-shakable tool library where unused icons will not be included in the final output, and your bundler will automatically handle this process for you.

Rendering effect. Iconfonts appear blurry when zoomed in on webkit-based browsers, while SVGs do not blur because they are vector graphics. Additionally, since iconfonts are generally loaded asynchronously, there may be issues with delayed rendering of icons.

Runtime modification. Due to React components' dynamic nature, we can modify the rendering effects of icons at runtime.

The reason for not using base64 scheme is due to size: Base64 encoding method increases code size compared to its original form which does not seem like an elegant solution.