nf-icons 0.1.0

Compile-time Nerd Font glyph lookup proc-macro.
Documentation

nf-icons: Compile-time Nerd Font glyph resolver

This crate provides the nf! procedural macro that resolves a glyph name as a string literal at compile time.

Usage

Run cargo add nf-icons or add the following to your Cargo.toml. MSRV is 1.85 (Rust edition 2024):

[dependencies]
nf-icons = "0.1"

nf-icons 0.1 bundles Nerd Fonts v3.4.0 glyph data. Each new Nerd Fonts release ships as a new breaking-change version of this crate.

Use the nf! macro to resolve glyph names:

use nf_icons::nf;

println!("{} close", nf!("nf-fa-xmark"));
println!("{} folder", nf!("nf-fa-folder"));
println!("{} rust", nf!("nf-dev-rust"));

To discover available glyphs and their names, visit the Nerd Fonts cheat sheet. Once you find a glyph, click Copy Class Name — the string it copies (for example, nf-fa-xmark) is exactly the key nf! expects. The nf- prefix is required so the cheat-sheet output works without editing.

Because nf!(...) expands to a &'static str, it works anywhere a string literal does — including const and static items:

# use nf_icons::nf;

const TAB_ICONS: &[(&str, &str)] = &[
    ("files",  nf!("nf-cod-files")),
    ("search", nf!("nf-cod-search")),
    ("git",    nf!("nf-cod-source_control")),
];

Unknown glyph names produce a compile_error! that looks like:

error: Unknown Nerd Font glyph `nf-fa-xmarkk`. Did you mean one of: `nf-fa-xmark`, `nf-md-marker`, `nf-oct-x_mark`?
 --> src/main.rs:4:24
  |
4 |     let close = nf!("nf-fa-xmarkk");
  |                        ^^^^^^^^^^^^^

Note: This crate does not ship any font. You need a Nerd Font installed and selected in whatever renders the output (terminal, editor, GUI toolkit).

Why a procedural macro?

The glyph table — roughly 10k entries from the current Nerd Fonts release — is baked into a perfect hash map (phf) when nf-icons itself is compiled. At your crate's compile time the macro performs an O(1) lookup and expands to a plain string literal, so there is no runtime cost, no embedded table in your binary beyond the glyphs you actually reference, and no risk of mistyping a glyph name and only discovering it after shipping.

How to update glyph data

Glyph names and codepoints are generated from the upstream glyphnames.json shipped with each Nerd Fonts release. To refresh against a newer release, update include/glyphs.json (the .justfile has an update-glyphs recipe that fetches the latest copy) and rebuild — build.rs will regenerate the perfect hash map.

License

Licensed under either of

at your option.