UI.Icon
luastra/uiUI.Icon(input: Input): Node
Renders one glyph from Luastra's bounded theme-aware icon set without adding a renderer component per glyph. Informative icons require a label; decorative icons are hidden from assistive technology.
Mental model
This is a declarative node: app.render describes it again from current state, while the host matches its stable id to the existing view.
Before you use it
Add luastra/ui to this module's dependencies in luastra.json, then import it with require("luastra/ui"). The project must declare the ui.render capability. app.render must return one UI.Screen root; place this node inside that tree rather than invoking it for a hidden side effect.
How it fits
The constructor validates its fields immediately and returns a UI.Node. After app.render returns, the host reconciles that node by stable id with the current semantic DOM-based interface. Current desktop and mobile hosts package the same web artifact; native adapters are used at capability boundaries.
When to use it
Use UI.Icon for non-interactive status or supporting imagery. Put an icon on UI.Button when it participates in an action, and use UI.Image for detailed or application-owned artwork.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique ID. |
| icon | bounded icon name, required | Theme-aware glyph selected from the built-in set. |
| decorative | boolean, required | Hides decorative glyphs from assistive technology. |
| label | string? | Required for an informative icon and forbidden for a decorative icon. |
| margin | none | xs | sm | md | lg | xl | All-side outer spacing. Group: Layout and surfaces. |
| marginX / marginY | none | xs | sm | md | lg | xl | Axis-specific outer spacing. Group: Layout and surfaces. |
| marginTop / marginBottom / marginStart / marginEnd | none | xs | sm | md | lg | xl | Logical side-specific outer spacing. Group: Layout and surfaces. |
| className | safe string ≤ 256 bytes | Additional admitted class tokens. Group: Layout and surfaces. |
| hidden | boolean | Visibility state. Group: State and semantics. |
| motion | { [property]: Tween | Sequence } | Opacity, rotation, scale, and translation channels. Group: Events and motion. |
Children and layout
This component does not accept arbitrary child nodes; named parameters provide its content.
Accessibility and keyboard
Informative icons expose a role and label; decorative icons are hidden. An Icon is never an action by itself.
Common mistakes
- Using an arbitrary glyph name.
- Giving a decorative icon a label or leaving an informative icon unnamed.
Returns
Node — a validated declarative UI node that becomes part of the next host-neutral render tree.
What happens next
A validated declarative node appears after it is returned as part of the current render tree.
Failures and fixes
Invalid fields, duplicate IDs, unsupported child combinations, or a missing ui.render capability fail during check, render-tree validation, or host startup.
Availability
Source API in 0.5.0-alpha; the public installer targets 0.5.0-alpha. Verify host-specific behavior against the selected SDK.
Focused example
local UI = require("luastra/ui")
return UI.Screen {
id = "app",
UI.Column {
id = "welcome/content",
gap = "md",
align = "center",
UI.Text {
id = "welcome/title",
text = "Welcome to Luastra",
variant = "title",
textAlign = "center",
},
UI.Button {
id = "welcome/start",
text = "Start",
onTap = "welcome.start",
},
},
}