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.
[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 themselvesThe 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")
}
}
}| Prop | Type | Default | Notes |
|---|---|---|---|
icon | Signal<IconData, LocalStorage>, into | required | a constant or a signal |
size | IconSize | Md | Sm, Md, Lg, Xl; a plain value, not a signal |
label | Option<String> | none | the accessible name |
class | Classes | none | merged after the icon's own classes |
| attribute bundle | Attrs | none | applied 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
| Written | In 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-iconandzui-icon--<size>, plus the generatedIconStyle::CLASS. Select on.zui-iconfrom your own sheet. data-size(sm,md,lg,xl) anddata-icon(the icon's name).prop:dwith the outline andprop:viewBoxwith0 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.
| Module | Constants | data-icon names |
|---|---|---|
arrow | ARROW_UP, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT | arrow-up, … |
chevron | CHEVRON_UP, CHEVRON_DOWN, CHEVRON_LEFT, CHEVRON_RIGHT | chevron-up, … |
mark | CHECK, MINUS, PLUS, CROSS, DISC, DOT | check, minus, plus, cross, disc, dot |
status | ALERT_CIRCLE, ALERT_TRIANGLE, INFO, CHECK_CIRCLE, CROSS_CIRCLE | alert-circle, alert-triangle, info, check-circle, cross-circle |
ui | SEARCH, SPINNER, ELLIPSIS, PANEL_LEFT | search, 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.
size | Reads | Fallback |
|---|---|---|
Sm | --zui-icon-sm | 12px |
Md | --zui-icon-md | 16px |
Lg | --zui-icon-lg | 20px |
Xl | --zui-icon-xl | 24px |
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):
| Rule | Why |
|---|---|
| Put all subpaths in one outline string | a hole must be cut from the shape it is inside |
| Wind a hole in the opposite direction | outlines fill with the non-zero rule; the same winding fills the hole |
| Close every subpath | an open path draws nothing |
| Stay inside the declared square | anything outside is cropped |
| Use a kebab-case name | it is written to data-icon |
| Design for 16 px | that 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 holepath() 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
Primitives
Reference for zgui-ui-primitives, the headless behaviours behind the component library — placement, focus trapping, roving focus, exit animations, dismissal, item order and value ownership — and how to style them with your own CSS.
Devtools
Open and use the zgui-devtools inspector: the element tree, computed style, frame counters, timeline, reactive scopes, style support and memory, plus writing a frame probe of your own.