zgui
Component library

Icons

Draw icons with zgui-ui-icons — the Icon component, the 23 shipped icons, sizing and colouring from CSS, and adding icons of your own.

zgui-ui-icons is a small icon set and one component, Icon, that draws an icon with the vector element. It depends only on zgui; you do not need zgui-ui or the tokens to use it.

Cargo.toml
[dependencies]
zgui-ui-icons = "0.1"
use zgui_ui_icons::prelude::*;                                // Icon, IconData, IconSize, IconVariants, IconStyle
use zgui_ui_icons::set::{chevron::CHEVRON_RIGHT, mark::CHECK}; // the icons themselves

The icons are not in the prelude, so import the ones you use. Each icon is a separate const, and a program links only the icons it names.

Draw an icon

#[component]
fn Item() -> impl IntoView {
    view! {
        row {
            Icon(icon = CHECK, size = IconSize::Sm)
            text {"Two-factor authentication"}
            spacer()
            Icon(icon = CHEVRON_RIGHT, label = "Open")
        }
    }
}
PropTypeDefaultNotes
iconSignal<IconData, LocalStorage>, intorequireda constant or a signal
sizeIconSizeMdSm, Md, Lg, Xl; a plain value, not a signal
labelOption<String>nonethe accessible name
classClassesnonemerged after the icon's own classes
attribute bundleAttrsnoneapplied after the icon's own attributes

icon can be a signal. A disclosure chevron is one element whose outline changes, not two branches:

let open = RwSignal::new_local(false);
view! {
    Icon(icon = Signal::derive_local(move || if open.get() { CHEVRON_UP } else { CHEVRON_DOWN }))
}

Accessibility

WrittenIn the accessibility tree
Icon(icon = CHECK)hidden; use this next to text that already says the same thing
Icon(icon = CROSS, label = "Close")an image named "Close"; use this when the icon is the only label

Rendered element

Icon renders one vector element with:

  • the classes zui-icon and zui-icon--<size>, plus the generated IconStyle::CLASS. Select on .zui-icon from your own sheet.
  • data-size (sm, md, lg, xl) and data-icon (the icon's name).
  • prop:d with the outline and prop:viewBox with 0 0 <side> <side>.

The icon sheet is installed once per window, however many icons are drawn. Each outline is parsed once and the result is cached by its text, so every element that draws the same icon shares it.

Available icons

23 icons in five modules under zgui_ui_icons::set. Each is drawn on a 24-unit square.

ModuleConstantsdata-icon names
arrowARROW_UP, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHTarrow-up, …
chevronCHEVRON_UP, CHEVRON_DOWN, CHEVRON_LEFT, CHEVRON_RIGHTchevron-up, …
markCHECK, MINUS, PLUS, CROSS, DISC, DOTcheck, minus, plus, cross, disc, dot
statusALERT_CIRCLE, ALERT_TRIANGLE, INFO, CHECK_CIRCLE, CROSS_CIRCLEalert-circle, alert-triangle, info, check-circle, cross-circle
uiSEARCH, SPINNER, ELLIPSIS, PANEL_LEFTsearch, spinner, ellipsis, panel-left

An icon is an IconData: a name, the side length of its square, and one outline in SVG path notation.

pub const MINUS: IconData = IconData::new("minus", 24.0, "M4 11 L20 11 L20 13 L4 13 Z");

name(), view_box() and path_data() return these values. path() parses the outline into a kurbo::BezPath for measuring or testing; drawing does not use it.

Set the size

size selects a custom property, and each property has a pixel fallback.

sizeReadsFallback
Sm--zui-icon-sm12px
Md--zui-icon-md16px
Lg--zui-icon-lg20px
Xl--zui-icon-xl24px

Each icon writes the resolved size to its own --zui-icon-size, which sets the width and height. So a container sets a step such as --zui-icon-md, and --zui-icon-size changes one icon only. The token crate has no icon group, so nothing declares the --zui-icon-* properties by default and the fallbacks are the actual sizes. Icons have flex: none, so a row does not stretch them.

// Every default-size icon in the window (application sheet):
//   :root { --zui-icon-md: 18px }

// Every default-size icon under one element:
view! { row(var:--zui-icon-md = "18px") { Icon(icon = CHECK) } }

// One icon:
view! { Icon(icon = CHECK, class = "tight") }
//   .tight { --zui-icon-size: 12px }

size is not a signal. To change an icon's size at run time, use a class or a var: binding.

Set the colour

There is no colour prop. An icon is filled with its computed color, like text. An icon in a destructive button is red because the button's text is red, and an icon in a disabled control fades with it. To recolour a group of icons, set color:

.zui-alert--destructive .zui-icon { color: var(--zui-color-destructive); }

fill and stroke in a style sheet have no effect: the style engine does not support the SVG paint properties. Set color, or set --zgui-fill when the icon must differ from the surrounding text.

Add your own icons

IconData::new is a const fn, so you write your icons the same way as the shipped ones:

use zgui_ui_icons::IconData;

/// A square with a square hole in it.
const FRAME: IconData = IconData::new(
    "frame",
    24.0,
    "M2 2 L22 2 L22 22 L2 22 Z M6 6 L6 18 L18 18 L18 6 Z",
);

view! { Icon(icon = FRAME, label = "Crop") }

The shipped set follows these rules (each is a test in crates/zgui-ui-icons/tests/geometry.rs):

RuleWhy
Put all subpaths in one outline stringa hole must be cut from the shape it is inside
Wind a hole in the opposite directionoutlines fill with the non-zero rule; the same winding fills the hole
Close every subpathan open path draws nothing
Stay inside the declared squareanything outside is cropped
Use a kebab-case nameit is written to data-icon
Design for 16 pxthat is the default size

You can check your own icons the same way:

use zgui::elements::kurbo::{Point, Shape};

let bounds = FRAME.path().bounding_box();
assert!(bounds.x0 >= 0.0 && bounds.x1 <= 24.0);
assert_ne!(FRAME.path().winding(Point::new(4.0, 12.0)), 0);  // the frame is solid
assert_eq!(FRAME.path().winding(Point::new(12.0, 12.0)), 0); // the middle is a hole

path() panics on notation it cannot parse, which such a test catches. A square other than 24 units is fine: the component writes whatever view_box declares, so a 32-unit icon and a 24-unit icon draw at the same size.

Draw an icon without the component

Icon is a thin layer over vector. Written by hand, an icon is one element:

view! {
    vector(
        class = "icon",
        prop:viewBox = "0 0 24 24",
        prop:d = "M20.5 7.1 L18.9 5.5 L9.6 14.8 L5.1 10.3 L3.5 11.9 L9.6 18.0 Z",
        a11y:hidden = true,
    )
}
.icon { display: inline-block; flex: none; width: 16px; height: 16px; }

For a whole SVG document, use prop:svg instead of prop:d and prop:viewBox. A document that uses fill="currentColor" follows the element's color; one with its own colours keeps them. See Vector and canvas.

Next

On this page