encre-css-icons

A plugin that provides a set of classes to use icons from Iconify based on the @unocss/preset-icons NodeJS package.

Features

• A lot of icon sets (you can use Icônes to search among them)
• Pure CSS icons
• Icons follow the text size
• Icons follow the text color
• Support colorful and monochrome icons
• No request is issued client-side when not using WebAssembly
• Supports WebAssembly (SVG icons will be directly fetch client-side)

Getting started

To integrate encre-css-icons with encre-css, add it in your Cargo.toml:

[dependencies]
encre-css-icons = "0.1.4"

Then, call the register function with a mutable reference to a Config structure and some parameters (all parameters are optional, you can use None to use the default value):

use encre_css::Config;

let mut config = Config::from_file("encre-css.toml")?;
// Or let mut config = Config::default();

encre_css_icons::register(&mut config);

// The convention is <prefix><collection>-<icon>
let _css = encre_css::generate(
    [r#"<h1 class="text-xl text-gray-600">Hello <span class="subway-world-1"></span>!</h1><div class="mdi-alarm block"></div><span class="fa-solid-home"></span><span class="openmoji-automobile hover:openmoji-autonomous-car"></span>"#],
    &config,
);
// Do something with the CSS

Configuration

This plugin has some configuration options, to set them simply add an extra field icons in the configuration with the fields you want to change. If configuring using Rust, the extra configuration must be added before registering the plugin. For example in TOML:

[extra.icons]
prefix = "i-"
custom-cdn = "https://cdn.skypack.dev"
scale = 1.2

Or in Rust:

use encre_css::{Config, toml};

let mut config = Config::default();
// Or let mut config = Config::from_file("encre-css.toml")?;

config.extra.add("icons", toml! {
    prefix = "i-"
    custom-cdn = "https://cdn.skypack.dev"
    scale = 1.2
});

// Then register the plugin
encre_css_icons::register(&mut config);

Configuration fields:

• prefix (default: ""): a static prefix added to all icons
• custom-cdn (default: https://esm.sh): the CDN used to get the SVG definition of icons (see the section below)
• scale (default: 1.0): the scale of icons used to change their size

Network requests and caching

Please note that, in order to get the SVG definition of icons, this crate will make requests to a (of course configurable) third-party CDN (the default CDN is https://esm.sh) and will cache them in the system's configured cache directory ($XDG_CACHE_HOME or $HOME/.cache on GNU/Linux, {FOLDERID_LocalAppData} on Windows, $HOME/Library/Caches on macOS), in a directory named encre-css-icons-cache.

Various tips and tricks

If searching the collection files takes too long (even if they are also cached in memory), it is recommended to optimize the encre-css-icons crate even in development, by adding the following in your Cargo.toml file:

[profile.dev.package.encre-css-icons]
opt-level = 3

By default, each icon has the display: inline-block; CSS property applied (even on div elements) otherwise they would be unsized when used in span elements. If you need to turn them into block elements, you can use the block utility class on each icon, e.g. <div class="fa-pencil block"></div>.

License

The code itself is under the MIT License. The collections of icons are under various licenses, see collections.md for a list of collections and their licenses.