Elements

Cuttlefish UI supports a focused set of HTML elements. Every UI has exactly one <screen> root; inside it you compose containers, text, controls, and media.

The <screen> root

<screen>
  ...children...
</screen>

Required. Exactly one per UI. Its box fills the display viewport (e.g. 320×240 landscape for an ILI9341, a common TFT display controller). All other elements live inside it.

Containers and text

<view> — generic container

A block container. Supports display: flex for layout. Exposes .value plus onToggle/onChange for pin-driven state.

<view id="row" style="display: flex; flex-direction: row; gap: 8px;">
  <text>Hello</text>
  <text>World</text>
</view>

<text> — static or dynamic text

<text id="label">Temperature</text>

Has a numeric .value property for state. To change the displayed string reactively, use ui.bind(node, 'text', compute) (see Authoring API).

Interactive elements

<button>

<button id="ok">OK</button>

Supports the :pressed pseudo-state and transition animations (see CSS). Events: onClick (short tap, up within 600ms), onHold (press ≥ 600ms), onRelease.

<check>

<check id="enable">Enable feature</check>

Content text is the label. .value is 0 (unchecked) or 1 (checked). onToggle(pin, onChange?) watches a GPIO pin for falling edges and flips .value automatically.

<radio>

<radio name="mode">Auto</radio>
<radio name="mode">Manual</radio>

Radios sharing the same name are mutually exclusive — selecting one deselects the others. .value is 0 or 1.

<select>

<select id="mode">
  <option>Auto</option>
  <option>Manual</option>
  <option>Off</option>
</select>

Tapping cycles through the <option> children. .value is the index of the current option (0..N-1); the element’s displayed text automatically reflects the current option.

<progress>

<progress id="load" value="40"></progress>

Read-only progress bar. .value is 0-100 (percentage filled).

<range>

<range id="brightness" min="0" max="100"></range>

A draggable slider. .value sits between min and max (defaults 0-100). onChange(callback?) fires whenever .value changes during a drag. Drag the thumb or write .value from code.

<input>

<input id="ssid" type="text" placeholder="Network name" maxlength="32">

Text input. Tapping opens an on-screen keyboard. The string value lives in .text (not .value). onChange(callback?) fires after the keyboard commits. Attributes: id, type, placeholder, maxlength.

<list>

<list id="networks" item-height="28px"></list>

A virtualized (only the visible items are drawn), data-bound list. Bind it to dynamic data with ui.bindList(node, countFn, itemFn, onTap?). Attribute: item-height.

<canvas>

<canvas id="spark" width="120" height="40"></canvas>

A user-drawn region. Register a per-frame draw callback with ui.drawCanvas(node, callback); the callback receives a CanvasCtx (see Authoring API). Attributes: width, height (drawing buffer size in pixels).

Images

<img>

<img id="logo" src="assets/logo.img" width="64" height="64">

Embeds a raw RGB565 (a compact color format) .img file (flat row-major, width × height × 2 bytes) as a static const uint16_t[]. Use object-fit: contain | cover | fill to control scaling. Attributes: id, src, width, height.

HTML tag aliases

Common HTML tags map to Cuttlefish primitives:

Global attributes

All elements support hidden — a hidden element (and its descendants) is kept in memory but takes no space on screen and ignores taps.

Next: CSS & Styling for how to style these elements.