UI.Grid
luastra/uiUI.Grid(input: Input): Node
Creates a responsive multi-column collection using two, three, or adaptive columns while retaining source order. Items reflow as available width changes instead of requiring manual breakpoint calculations.
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.Grid for galleries, dashboards, feature cards, and repeated items of comparable importance. Use Table for relational data and Row when content must remain one-dimensional.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique ID. |
| children | UI.Node[] | Cards or other repeated grid items. |
| gap | none | xs | sm | md | lg | xl | Space between children. Group: Layout and surfaces. |
| padding | none | xs | sm | md | lg | xl | responsive | All-side inner spacing; responsive is supported only by padding. Group: Layout and surfaces. |
| margin | none | xs | sm | md | lg | xl | All-side outer spacing. Group: Layout and surfaces. |
| paddingX / paddingY | none | xs | sm | md | lg | xl | Axis-specific inner spacing. Group: Layout and surfaces. |
| paddingTop / paddingBottom / paddingStart / paddingEnd | none | xs | sm | md | lg | xl | Logical side-specific inner 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. |
| surface | plain | card | elevated | accent | Background, border, and elevation. Group: Layout and surfaces. |
| width | full | content | wide | Available width, 720 px maximum, or 1180 px maximum. Group: Layout and surfaces. |
| align | start | center | end | stretch | between | Cross-axis alignment. Group: Layout and surfaces. |
| justify | start | center | end | between | Main-axis alignment. Group: Layout and surfaces. |
| flow | wrap | nowrap | Flex wrapping. Group: Layout and surfaces. |
| columns | adaptive | two | three | Grid columns. Group: Layout and surfaces. |
| responsive | boolean | Narrow-screen adaptation. Group: Layout and surfaces. |
| className | safe string ≤ 256 bytes | Additional admitted class tokens. Group: Layout and surfaces. |
| tone | muted | error | success | Semantic text tone. Group: State and semantics. |
| appearance | primary | secondary | danger | ghost | Action appearance. Group: State and semantics. |
| variant | body | subheading | heading | title | Body text or h3, h2, and h1 heading semantics. Group: State and semantics. |
| role | alert | group | status | Supported ARIA role. Group: State and semantics. |
| label | string | Accessible name. Group: State and semantics. |
| hidden | boolean | Visibility state. Group: State and semantics. |
| disabled | boolean | Disabled state. Group: State and semantics. |
| busy | boolean | aria-busy state. Group: State and semantics. |
| required | boolean | Required input state. Group: State and semantics. |
| errorId | component id | Associates a visible role=alert. Group: State and semantics. |
| textColor | token | #RRGGBB | Local or inherited foreground. Group: Text and local colors. |
| backgroundColor | token | #RRGGBB | Component-box background. Group: Text and local colors. |
| Color tokens | accent | danger | muted | surface | success | text | transparent | warning | Current Screen theme colors. Group: Text and local colors. |
Children and layout
Cards or other repeated grid items.
Accessibility and keyboard
A stable id, logical render-tree order, and visible labels preserve predictable keyboard and screen-reader navigation.
Common mistakes
- Using a duplicate id or an uppercase path segment.
- Passing a shared-group parameter that is not listed on this component page.
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
UI.Grid {
id = "catalog/grid",
width = "full",
columns = "adaptive",
gap = "md",
UI.Card { id = "catalog/one", UI.Text { id = "catalog/one/title", text = "One" } },
UI.Card { id = "catalog/two", UI.Text { id = "catalog/two/title", text = "Two" } },
}