UI.Image
luastra/uiUI.Image(input: Input): Node
Displays packaged Assets.Image and dynamic Content.Image references through one component. Bounded metadata, placeholders, load/error actions, fit, clipping, and an accessible label stay independent of the storage provider.
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.Image for packaged, protected, or host-local preview PNG, JPEG, WebP, or AVIF content. Use UI.Shape for scalable geometry, refresh expired content after onError, and supply a meaningful label unless the image is genuinely decorative.
Shared parameter groups
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| id | lowercase path, required | Unique ID. |
| source | Assets.Image | Content.Image | legacy asset URI | Typed packaged, protected, or host-local preview image. |
| placeholder | Assets.Image? | Optional packaged image shown behind loading content. |
| onLoad / onError | action string? | Dynamic image lifecycle actions. |
| label | string, required | Accessible description; an empty string marks a decorative image. |
| 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. |
| placeholderColor | #RRGGBB | Stable loading background color. Group: Image, Shape, and FlipCard. |
| fit | contain | cover | fill | none | scaleDown | Image scaling. Group: Image, Shape, and FlipCard. |
| width / height | 1…4096 | CSS-pixel size. Group: Image, Shape, and FlipCard. |
| aspectRatio | 0.05…20 | Aspect ratio. Group: Image, Shape, and FlipCard. |
| cornerRadius | 0…2048 | Corner radius. Group: Image, Shape, and FlipCard. |
Children and layout
This component does not accept arbitrary child nodes; named parameters provide its content.
Accessibility and keyboard
label is required; use an empty string only for a genuinely decorative image.
Common mistakes
- Passing a filesystem path, arbitrary URL, provider-signed URL, or raw blob instead of a typed image reference.
- Omitting the required label or failing to refresh an expired dynamic handle after onError.
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 Assets = require("luastra/assets")
UI.Image {
id = "card/back",
source = Assets.image("image/card-back"),
width = 274,
height = 382,
fit = "cover",
label = "Card back",
}Continue with a complete recipe
This checked recipe uses UI.Image inside complete authored files with the required manifest, test, and run steps.
Open package an image and compose visuals recipe