Components
Components are the visual parts you see on the screen: labels, buttons, toggles, charts, images, and more. You combine them to build what a data piece, a Freeform section, or a custom screen shows.
Where you use them
- On a data piece — open the data piece editor and tap +. A new data piece already has a Header label and a Data source activity bar group.
- On a Freeform section — components can sit right on the canvas, next to data pieces. With Edit layout on, tap Add at the top, then Add component. See Main screen.
- On a custom screen — each layout of a custom screen is built from components. See Custom screens.
+ (or Add component) opens the library. Components lists every single component. Grouped has ready-made groups and groups you saved. On a Freeform section, the library also has Data pieces, with ready-made data pieces and data pieces you saved. See Data piece library.
Arrange them
- Tap a component to select it. Drag it to move it, drag a side or corner to resize it, and use the handle at the top-right to rotate it.
- Long-press it for more options such as Copy, Cut, Duplicate, Paste, and Delete. On a Freeform section on the home screen, tap the component, then tap its menu button instead of long-pressing.
- To select several, long-press a component, choose Select more, tap the others, then tap Done. On iPad with a mouse or trackpad, you can also drag a frame over empty space. Drag any selected component to move them all together.
- Use Wrap in group to keep selected components together. A group moves and scales as one. Edit contents opens what is inside it; Ungroup splits it again. Save to library keeps a group under Grouped so you can reuse it.
- Moving and resizing always snap to a grid. Grid size under the preview makes the grid finer or coarser. Data pieces, groups, custom screens, and bottom sheets each keep their own size on this device.
- Tap Help above a selected component to open the in-app guide for that component. It lists every property and shows script examples.
Copy and paste
Copy components to reuse them in another place: another data piece, a group, a custom screen, or a Freeform section.
- Long-press a selected component, or tap the menu handle under it, for Copy, Cut, Duplicate, and Paste. With several components selected, these work on all of them.
- Long-press the empty canvas for Paste, and Select all when there are components.
- On iPad with a keyboard, hold Cmd and press C to copy, X to cut, V to paste, D to duplicate, or A to select all. While you type in a text field, these keys copy and paste text as usual.
- A Freeform section selects one item at a time, so it has no Select all, and copy, cut, and duplicate work on the selected component.
- You can paste in the data piece editor, in a group's contents, in the custom screen designer, in a saved group, and on a Freeform section while Edit layout is on. The copy stays on the clipboard after you restart the app, and it can move to another device that shares your clipboard.
- Pasting in the same place puts the copy one grid step down and to the right. Each further paste moves one more step. On a Freeform section, a paste on the same canvas goes to the nearest free spot instead, like Duplicate. Pasting somewhere else keeps the position and fits the new shape. Cut and then Paste in the same place puts the components back where they were.
- Duplicate puts a copy next to the original and does not change the clipboard.
- Cut removes the components right away, without asking.
What happens to the copy:
- A pasted component keeps its ID when no other component uses it. Otherwise the name stays and a number is added or increased:
temp_labelbecomestemp_label2, andlabel1becomeslabel2. Scripts and expressions in the pasted components that refer to each other (components.<id>) switch to the new IDs. References to components you did not copy stay as they were. - A component that used the data source of its data piece or group now uses the source of the place you paste it into. A data source you picked on the component itself is kept. If that source does not exist there, the component shows Data source not found.
- A group cannot go inside another group. When you paste into a group's contents, groups are skipped and a message tells you. Components copied from inside a group can be pasted onto the data piece.
- Without Pro, data pieces hold up to 200 components in all sections together, all sections hold up to 30 data pieces and Freeform components together, and custom screens and bottom sheets hold up to 30 components across all of them. A paste that would go over a limit opens Plans and adds nothing.
- On a Freeform section, only components and groups are copied this way. Data pieces keep Duplicate and Move in their own menu.
- The copy is plain text on the clipboard.
Settings every component has
- Data source — by default a component uses the root data source of its data piece, Freeform section, or custom screen. Pick another one when this component needs different data.
- Inherited — when on and the component uses the same source as its parent, it starts from the parent's value after the parent's transformers. Turn it off to add this component's own Data transformers pipe. See Data transformers.
- Events — tap actions such as On tap, On long press, On tap hold, or On change, depending on the component. See Tap actions.
- ID — a short name such as
label1, used by scripts. - Visible, Disabled, Opacity, Touches (Capture or Pass through), Anchor X, Anchor Y, and Rotation. Many components also have Border radius.
- Lock — keeps the component from being moved, resized, or rotated in the editor by mistake. It does nothing on the dashboard and scripts cannot change it.
- Data — your own notes or data, up to 5120 characters: plain text or JSON. It is always the last setting. It is stored as is and not evaluated, so
{{ }}is not replaced.- Scripts can read it as
comp.userData(andcomponents.label1.userDatafor another component of the same data piece) but cannot change it. The type is detected: text that is a JSON object or array becomes a Lua table (an object or array in JavaScript),true/falsea boolean, a plain number a number, anything else stays text. - The AI assistant may store data here on components it creates when something needs to be remembered.
- Do not put secrets here: it is part of your saved configuration and the AI assistant can see it.
- Scripts can read it as
Catalog
| Component | What it is for | Key properties |
|---|---|---|
| Label | One piece of text: a name, a reading, or a short message | Default value, Text size, Word wrap, Max lines, text alignment, Monospace, Text decoration, Background color |
| Badge | Short text on a colored pill | Default value, Background color, Gradient color |
| Chip | A short tag that can show an icon, a checkmark, or a delete mark | Selected, Selected color, Checkmark, Delete icon, Filled, Border color |
| Alarm banner | A colored strip with a message that shows only while there is an alarm (hidden when the value is empty, 0, false, off, or no) |
Default value, Text alignment X, Icon, Blink, Background color |
| Data source last activity label | How long ago the data source last received data | Prefix, Time format, text style |
| Clock | The current time, as digits or as a dial with hands; needs no data source | Clock style, 24-hour clock, Show seconds, Show date, Date format, UTC offset |
| HTML | Formatted text with bold, links, and simple markup | Default value (HTML) |
| Button | A labeled button you tap, with an optional icon | Style, Background color (fills the Filled and Tonal styles; the text follows it), Icon, Word wrap, Monospace |
| Icon button | A tappable icon with no caption | Icon, Icon size, Icon color, Filled (off shows only the icon, with no background), Background color, Fill box (fills the whole box instead of a circle; rounded ends by default, lower Border radius for square corners), Border color, Border width |
| Segmented button | A row of choices; one is selected. Set Content to Icons to show an icon per item | Content, Items, Icons, Default value, Selected color |
| Toggle | An on/off switch | On value, Off value, Active color, Inactive color, Caption position |
| Checkbox | A box you check, with a label beside it | Default text, On value, Off value, Active color, Caption position |
| Radio | A list of choices; one is selected | Items, Default value, Active color, Orientation (one column, or all items in one row) |
| Menu | Shows the current choice and opens a list on tap | Items, Default value |
| Slider | A track with one handle | Minimum, Maximum, Step, Orientation, Value label, Tick marks, Stroke width, Stroke color, Handle color, Handle icon, Handle size |
| Range | A track with two handles that mark a span | Minimum, Maximum, Step, Orientation, Value label, Tick marks, Stroke width, Stroke color, Handle color, Handle icon, Handle size |
| Circular slider | A ring with one handle; drag the handle around the ring | Minimum, Maximum, Step, Start angle, Arc, Value label, Stroke width, Track color, Handle color, Handle size |
| Knob | A round knob you turn by dragging up or down | Default value, Minimum, Maximum, Step, Value label, Track color, Knob color, Indicator color, Color |
| Number stepper | A number with − and + buttons; each tap changes it by Step | Default value, Minimum, Maximum, Step, Suffix, Icon color |
| Joystick | A round base with a stick; drag the stick to send a direction (x and y, from −1 to 1) |
Directions, Interval (ms), Decimals, Color, Stick color, Background color |
| Text input | A plain box you type into | Hint, Max length, Keyboard |
| Text field | An outlined box you type into; can hide the text for passwords | Hint, Icon, Clear button, Hidden text, Show/hide button, Max length, Keyboard |
| Highlight editor | Code or other text, colored for its language | Language, Read only, Line numbers |
| Date picker | Tap to choose a day (yyyy-MM-dd) |
Earliest, Latest |
| Time picker | Tap to choose a time (HH:mm) |
24-hour clock, Minute step, Show icon |
| Color picker | A hue ring. The color code (#RRGGBB), the selected color circle, and a lightness slider can be shown in the middle (hidden by default) |
Stroke width, Thumb size, Show color code, Show selected color, Show lightness slider, Text size |
| Linear progress | A bar that fills from minimum to maximum | Minimum, Maximum, Orientation, Reverse, Rounded ends |
| Circular progress | A ring that fills from minimum to maximum | Minimum, Maximum, Thickness |
| Dial gauge | A needle on a round scale, like a speedometer. Warning and alarm zones color the scale | Minimum, Maximum, Tick marks, Warning from, Alarm from |
| Linear gauge | A ruler with numbers; a bar and a pointer show the value, with optional warning and alarm zones and the value as text above it | Minimum, Maximum, Orientation, Tick marks, Warning from, Alarm from, Value label |
| Chart | A series of numbers as a line, area, bars, or pie; line, area, and bars can show several named series | Chart type, Max points, Save series on disk, Series field, Labels, Legend, X-axis title, Y-axis title |
| Data table | Rows and columns from JSON data | Header, Striped rows, Grid, Density, Columns, Sort by, Max rows, Decimals, Thousands separator, Number alignment |
| Timeline | Events as a list: a dot on a line for each, with title, time, and detail | Default value, Title field, Time field, Detail field, Color field, Reverse, Max items, Dashed line, Color |
| Image | A picture from a web address, SVG text, or image data | Fit, Placeholder, Tint color, Border radius |
| Video | Live pictures from a camera: from a Video data source, or pictures that arrive as MQTT or WebSocket messages (PNG, JPEG, GIF, or WebP; other messages are ignored, and the last picture stays) | Fit, Alignment, Border radius |
| Icon | A glyph with no caption and no tap of its own | Icon, Icon color |
| Shape | A filled figure: circle, star, arrow, heart, gear, speech bubble, pie slice, and more | Shape, Stretch to fill, Fill color, Border color, Border width. Some shapes add their own: Points (star), Teeth (gear), Inner size (star, ring, gear), Start angle and Arc (pie slice), Corner rounding (shapes with corners) |
| QR code | A square code that a phone camera can read. It encodes the value, such as a web address | Default value, Color, Background color |
| Status dot | A dot whose color follows the data source: its activity and errors, or its connection | Shows (Data source activity or Connection) |
| Wait animation | A small loading motion | Animation |
| Divider | A thin line between areas | Orientation, Dashed line |
| Panel | A filled rectangle to put behind other components | Background color, Gradient color, Border |
| Empty group | Holds other components so they move together; can have its own data source, transformers, tap actions, and Periodic action pipes | Background color, Gradient color, Border, Clip contents |
Grouped starts with Empty group and one ready-made group, Data source activity bar.
Text components share Text size, Text color, Bold, and Italic. Button, Checkbox, Radio, Menu, and Segmented button also have Fit width to content. Items takes one item per line, comma-separated text, or a JSON array.
What interactive components send
When you use a control, its Events run with a value. It is value in the first action of the list.
| Component | Event | value |
|---|---|---|
| Slider, Circular slider, Knob | On change / On changed | The number while you drag / the final number when you let go (Knob: only if it changed) |
| Range | On change / On changed | [low, high] while you drag / when you let go |
| Color picker | On change / On changed | The color as #RRGGBB |
| Joystick | On change | {x, y}, each from −1 to 1 (right and up are positive), rounded to Decimals. Runs every Interval (ms) while you hold the stick, then once with 0 and 0 when you let go |
| Joystick | On changed | {x: 0, y: 0}, once when you let go |
| Toggle, Checkbox | On tap | The current on or off value. The ready-made actions flip it and apply it |
| Radio, Menu, Segmented button | On tap | The item you chose |
| Number stepper | On tap | The new number |
| Toggle, Checkbox, Radio, Menu, Segmented button, Number stepper | On change | The value On tap ended with |
| Text input, Text field, Highlight editor | On change | The text, as you type |
| Date picker / Time picker | On change | The day as yyyy-MM-dd / the time as HH:mm, when you confirm a new pick |
| Button, Icon button | On tap | The incoming value, or Default value |
| Chip | On delete | The label |
| HTML | On link tap | The link address |
| Data table | On row tap | The row, as {column: cell} |
| Chart | On point tap | {value, label, index, series} |
| Any component with it | On long press | The current value of the control, or the incoming value |
Clock, Icon, Shape, Panel, Divider, and Wait animation don't use incoming data. Status dot and Data source last activity label show the state of the data source, not its value.
A control does not change its data source. A control that uses a data source shows the source's value, but moving it does not send anything back. To change the device or the server, add a send action — MQTT send, HTTP request, or Trigger data destination — to On change, On changed, or On tap. See Tap actions.
Pick the state a control or gauge shows. On Toggle, Checkbox, Radio, Menu, Segmented button, Slider, Range, Circular slider, Knob, Number stepper, the progress bars, and the gauges, an expression in Default value is the live value. A new one that uses a data source starts with {{ value }}, which shows the incoming value as it is.
When the state is one field of the data, change it to that field, for example {{ value.enabled }} for a Wi-Fi switch or {{ value.rssi }} for a gauge. A tap shows its new value until the next data arrives. A typed Default value is shown only until the first data arrives.
In the component settings, the How it works banner explains this for the selected component, and each row under Events has a line value = … that says what that event receives.
Change a component while the app runs
There are two ways to make a component react to data, besides showing its value.
Use an expression for a property. Long-press a property row in the component settings and choose Simple expression. Type a simple expression between double braces, for example {{ value.temp > 30 ? "red" : "primary" }} for Text color. It can read value, ctx, env, and other data sources.
To go back to a fixed value, long-press the row again and choose the regular control, such as Use color or Use switch. On a Border row, each part has its own choice, such as Width: use expression.
Change it from Lua or JavaScript. In a transformer, a tap action, or a periodic action pipe, a script can set comp.<property> (the component that owns the script) or components.<id>.<property> (any component by its ID):
components.label1.textColorId = "red"
components.label1.visible = true
These changes show right away and are not saved. The next run of the same script replaces them. A script cannot change ID, Data source, Inherited, width, or height. Simple expression and JSONPath can read comp and components, but only Lua and JavaScript can change them. See Lua and JavaScript.
For every property name and more examples, open Help on a selected component in the app.