Components · Media
Image
An uploaded image (PNG, JPEG, GIF, WebP, or AVIF), shown at up to its natural size. file is the id from files_finalize; alt describes it for screen readers. ratio (square, photo 4:3, video 16:9, wide 21:9, portrait 3:4) fills the width and crops to that shape; fit: "contain" shows all of it instead; radius rounds it.
ExamplesLink to this section
The docs show a stand-in picture. On a real artifact, `file` is the id files_finalize returned.

Show JSONHide JSON
{
"version": 1,
"root": "image",
"elements": {
"image": {
"type": "Image",
"props": {
"file": "7d2c0c9e-4a51-4f53-9a7e-0f1d1e2c3b4a",
"alt": "Architecture diagram: agents reach the API over MCP",
"caption": "How agents reach the API."
}
}
}
}

Show JSONHide JSON
{
"version": 1,
"root": "grid",
"elements": {
"grid": {
"type": "Grid",
"props": { "columns": 2 },
"children": ["wide", "square"]
},
"wide": {
"type": "Image",
"props": {
"file": "7d2c0c9e-4a51-4f53-9a7e-0f1d1e2c3b4a",
"alt": "Architecture diagram, cropped wide",
"ratio": "wide",
"radius": "xl"
}
},
"square": {
"type": "Image",
"props": {
"file": "7d2c0c9e-4a51-4f53-9a7e-0f1d1e2c3b4a",
"alt": "Architecture diagram, shown whole in a square",
"ratio": "square",
"fit": "contain",
"radius": "lg"
}
}
}
}PropsLink to this section
Generated from the zod schema the server validates with. Unknown props are ignored with a warning. Any prop can also be a dynamic value such as { "$state": "/path" }; it is checked again once it resolves.
| Prop | Type | Limits and defaults |
|---|---|---|
| filerequired | string (uuid) | — |
| altrequired | string | max 300 chars |
| caption | string | max 300 chars |
| ratio | "square" | "photo" | "video" | "wide" | "portrait" | — |
| fit | "cover" | "contain" | — |
| radius | "none" | "sm" | "md" | "lg" | "xl" | "full" | — |
RulesLink to this section
fileis the id of a finished upload attached to this artifact. URLs are refused.filemust be written in the spec, not read from state, so saving can check it.- PNG, JPEG, GIF, WebP, and AVIF. The image shows at up to its natural size.
ratiocrops the image to a shape (fit: "contain"shows all of it instead), andradiusrounds its corners.
Children and eventsLink to this section
Image is a leaf: it does not show children. Validation warns when a leaf has some; wrap them in a Stack or Card instead.
It emits no events.