icon_en.md 5.7 KB
Starting from v1.1.0, STDF supports using icons via Iconify.
SVG Sprites
The STDF icon component's type defaults to symbol, which uses SVG Sprites technology to display icons. This reduces HTTP requests and improves page performance.
STDF's SVG Sprites use SVG symbol. The principle is similar to CSS Sprite technology, where SVG files in the project are concatenated into a single file, and the corresponding icon is displayed through the use element in SVG.
You can think of it as a font, except this font is composed of SVG and can be controlled for color, size, and other properties through CSS. Therefore, if you need to use large or complex icons with multiple colors, it's recommended to import SVG files separately rather than putting them in symbols.
Compatibility is also completely fine. Refer to MDN symbol.
STDF has developed a Rollup/Vite plugin for merging SVG files in projects into SVG Sprites. For specific usage, please refer to rollup-plugin-stdf-icon. Due to the diversity of SVG formats, there may be cases where rollup-plugin-stdf-icon doesn't process accurately. Please submit an issue on GitHub with specific details about the SVG file.
Alternatively, you can use other SVG Sprites synthesis tools or manual synthesis, or ask designers to provide corresponding SVG Sprites along with design materials. Or use icon libraries like Remix Icon, which allows you to directly download multiple selected icons as SVG Sprites.
Iconify
STDF can also use icons via Iconify by setting type to iconify or iconify-color.
Iconify has many usage methods. STDF chooses the Tailwind 4 plugin approach, which has minimal code intrusion. Refer to Iconify for Tailwind CSS. The usage in STDF is as follows:
- Install the Tailwind 4 plugin
pnpm i -D @iconify/tailwind4
npm i -D @iconify/tailwind4
bun i -D @iconify/tailwind4
yarn add @iconify/tailwind4
- Install the required open-source icon libraries
Installing
@iconify/jsonis strongly discouraged as the full icon library has a very large size.
Install icon libraries on demand. For example, use the following commands to install Solar and Carbon icon libraries:
pnpm i -D @iconify-json/solar
npm i -D @iconify-json/solar
bun i -D @iconify-json/solar
yarn add @iconify-json/solar
pnpm i -D @iconify-json/carbon
npm i -D @iconify-json/carbon
bun i -D @iconify-json/carbon
yarn add @iconify-json/carbon
Configure the plugin in your project's entry CSS file and set the icon library prefixes you need to use. Refer to Clean selectors.
@plugin "@iconify/tailwind4" { prefixes: solar, carbon; }Use icons in components
<Icon type="iconify" name="solar--cat-broken" />
The difference between using iconify and iconify-color is that iconify renders icons as mask images, where the icon color is the text color. Therefore, like using symbol, you can set the theme property to control the icon to follow the theme color, or set text color to customize the color. This is generally used for monochrome icons. While iconify-color renders icons as background images, you cannot set the theme property or customize colors with text color. This is generally used for multi-color icons, such as fluent-color icon libraries. Refer to extra-class-name.
How to choose?
Generally, there are several ways to use svg icons in STDF projects.
Use svg files directly without any processing. You can use the svg tag directly without using the Icon component, but it will increase HTTP requests and project size, and it is also not convenient to adjust the attributes of these icons uniformly. Generally used for large and complex svg images, not recommended for processing small svg icons.
Use the rollup-plugin-stdf-icon plugin. Merge the svg files into SVG symbol after compilation, but the svg files must conform to the standard, otherwise they may not be merged correctly. Recommended.
Use Iconify. Iconify's advantage is that the icon library is very rich, saves the trouble of finding icons, but requires manual installation of icon libraries and configuration plugins, and there may be some redundant icons in the project. Recommended.
Already have a merged SVG symbol file. Some icon libraries support exporting SVG symbol files, some other tools support merging svg into SVG symbol files, or the material provided by the designer is already a SVG symbol file, then you can use the merged SVG symbol file path directly without using rollup-plugin-stdf-icon and Iconify. Recommended depending on the situation.
Of course, these methods are not mutually exclusive, and a project may use multiple methods at the same time.