`image` element

A picture from your assets, a URL, or a record.

Renders

<img> (lazy by default) inside a sized wrapper when ratio is set

Required

source (or binds.source). alt is a warning when missing: use "alt": "" for decoration.

Native apps

Compiled native apps and server-driven apps

Syntax

image element

{ "type": "image" }

An element lives in a screen's sections, another element's elements, a layout slot or a component root.

Properties

Property	Type	Default	Description
`source`	`string`	—	image/video/audio/svg URL or assets path
`alt`	`string`	—
`loading`	`"lazy""eager""priority"`	`lazy`	image: lazy (default) waits until it nears the screen; eager loads at once; priority also asks for it first — use it for the picture people see first (often the largest paint)
`fit`	`"cover""contain""fill""none"`	—
`ratio`	`string`	—	ratios look like 16/9
`binds`	`object {name: string}`	—	bind attributes: {"source": "image", "target": "slug"}

Plus the properties every element accepts: id, className, style, responsive, states, animation, visible, ariaLabel, attributes and more.

Example

image example

{
  "type": "image",
  "source": "/assets/lamp.svg",
  "alt": "A brass desk lamp",
  "ratio": "4/3",
  "fit": "contain",
  "loading": "priority"
}

source may be an /assets/… path (checked at compile time), an https:// URL, or a non-SVG data:image/…. Bound images use "binds": {"source": "image", "alt": "name"}. Use loading: "priority" for the largest picture above the fold.

Expected output

The HTML IWC rendered for the example above (inside the page's content wrapper). Class names such as i807b63fc are generated per element for its scoped CSS.

Rendered HTML

<div class="iwc-page ipage" id="iwc-content">
  <img class="iwc-image i66211ca5" src="/assets/lamp.svg" alt="A brass desk lamp" fetchpriority="high">
</div>

Data, conditions & styling

Conditional rendering: "visible": {"auth": "signed-in"}, {"roles": ["admin"]} or an expression such as "=product.stock > 0". Decided on the server: hidden elements are never sent.
Data binding: bind takes text from data (name, user.name, props.title, params.slug, state.cart.count); binds binds attributes. Containers become data-driven with data + item. See data binding.
Styling: className for your stylesheets, style for CSS in JSON, states for hover/focus/active, animation for entrance motion. See the style property reference.
Responsive behaviour: responsive applies CSS at or below a breakpoint ({"mobile": {"padding": "12px"}}); grids also take responsiveColumns.