Custom screens
A custom screen is a layout of components that you design once and open with a tap. Use it for a details view, a control panel for one room, or anything that does not fit on a data piece. Several data pieces or components can open the same screen and pass it different values.
To show a layout over the current screen instead of a whole screen, use a custom bottom sheet.
A custom screen is not a zoomed data piece. To make one data piece bigger, use Data piece full screen instead. A custom screen is not a Freeform section either: a section is always on the main screen, while a custom screen is shown only when an action opens it. Both are compared at the end of this page.
Create a screen
Open the menu → Data → Custom screens, then tap Add custom screen.
- Name (required, unique) — shown at the top when the screen is open.
- Description (required) — what the screen is for. It helps you, and the AI assistant, pick the right screen later.
- Default root data source — the data source components use unless they pick another one. It is used while you design, and Open screen can replace it.
- Data — your own notes or data, up to 5120 characters, as plain text or JSON. It is different from Description: it is for data, not for saying what the screen does. It is stored as is and not evaluated, and scripts cannot read it. Don't put secrets there.
Save with the check in the top bar. In the list, long-press a screen to duplicate or delete it. Swipe a row right to left to delete it.
Without Pro you can use two custom screens and two bottom sheets, with up to 30 components across all of them (both layouts count). A group counts as one, and so does each component inside it. When you reach a limit, the app opens Plans. Screens you already have over a limit keep working, and you can still edit them. See Plans.
Vertical and horizontal layouts
Each custom screen has two layouts:
- Vertical screen — used when the device is upright. Aspect ratio: 10:16 (default), 9:16, 9:18, 9:20, or 3:4.
- Horizontal screen — used when the device is on its side. Aspect ratio: 16:10 (default), 16:9, 18:9, 21:9, or 4:3.
The horizontal layout is not a rotated copy of the vertical one. Design each so its components fit. If one layout is Empty, the screen uses the other one. More (⋯) in the designer offers Copy layout contents, to copy from the other layout or replace it with this one.
An open screen keeps its aspect ratio and sits in the middle of the display, with empty bands around it if needed. It does not stretch, and it has no pinch to zoom. Close it with Back.
Design a layout
Tap Vertical screen or Horizontal screen to open the designer. Changes apply as you work.
- + opens the component library (Components and Grouped). See Components.
- Move, resize, rotate, group, copy, paste, and edit components the same way as in the data piece editor. The grid is finer here, and Grid size is kept separately for screens and for bottom sheets.
- Unlike a new data piece, a new layout starts empty: no Header label and no Data source activity bar. Keep components a little in from the edges.
- Components have their own transformers and tap actions.
- With nothing selected, you can change the screen's Default root data source and add Periodic action pipes that run while the screen is open. In those pipes, use
components.<id>; there is nocomp. See Periodic action pipes. - With nothing selected, Events has On open and On close: actions that run when the screen opens and closes. See On open and On close.
Screen parameters
A screen can show values passed in when it opens. In labels, transformers, and tap actions write params.room, {{ params.room }}, or $.params.room. You do not declare keys first.
If Open screen does not pass room, text shows <room>. You see the same placeholders while designing. An empty value you pass stays empty.
Keys use lowercase letters, digits, and underscores, and start with a letter or underscore. source is reserved for the data source (see below).
Open a screen from a tap
On a data piece or a component, add the Open screen tap action, choose Custom screen, pick the screen, then set Screen parameters.
source — which data source the screen's components start from:
| Mode | What it uses |
|---|---|
| Inherit | The source of the screen that opened this one, then this data piece's or component's source, then the screen's Default root data source |
| Screen default | The screen's Default root data source |
| None | No data source |
| Choose data source | A data source you pick |
Other keys — tap Add key, then pick a mode:
| Mode | What it passes |
|---|---|
| Inherit | The same key from the screen that opened this one. If there is none, text shows <room> |
| Custom value | Text you type. It can include {{ value.room }}. Empty stays empty |
For example, give each room's data piece its own root source and an Open screen action with source set to Inherit and room set to a custom value. One screen then shows whichever room you tapped.
You can open a custom screen from another custom screen. Each one opens on top; Back closes the top one. Toggles, wait animations, and values stay with that open copy. If a tap points at a screen that was deleted, the action shows Missing custom screen until you change it.
Returning a value
A custom screen or a custom bottom sheet can send a value back to the tap that opened it. Use it for a picker ("which device?"), a short form, or a confirm panel. The value arrives once, when the screen closes.
Set the value on the screen
- Close screen has a Result field. Type a
{{ }}template, for example{{ value }}. The value becomes the result of the screen picked in Screen to close, and then that screen closes. Leave Result empty to just close; a value stored earlier with Set screen result is kept. Result is not offered with All screens. If the screen being closed is not a custom screen or bottom sheet, the result is ignored. - Set screen result stores the result on the screen or sheet it runs on and leaves it open. Use it in a component's tap, long press, or change actions, in the screen's Periodic action pipes, or in On open and On close. Each run replaces the earlier result, and an empty Result clears it. Outside a custom screen or bottom sheet, for example on a data piece on the main screen, the action fails with a message.
However the screen closes — Close screen, Back, swiping a sheet down, a tap outside it, or closing a screen below it — the tap that opened it gets the last stored result. If nothing was stored, it gets no result.
What kind of value arrives. When Result is a single placeholder, like {{ value }} or {{ ctx.result }}, the value keeps its type: an object, a list, a number, or true/false. Anything else — text around a placeholder, or several placeholders — gives text. Plain text without {{ }} is sent as that text. If the template can't be evaluated, nothing closes and the action fails.
Use the value in the opener
Open screen (with Custom screen) and Open bottom sheet wait until the screen closes, then run the actions after them. Two settings decide what happens with the result:
- Apply result — Pipeline value (the default) puts the result in
value, the same way a User input action does. ctx key stores it inctx.<name>and leavesvalueas it was. - If closed without a result — Continue (the default) runs the next actions with
valueandctxunchanged. Stop actions skips the rest of the list, like a cancelled prompt.
Later actions read the result as {{ value }} or {{ ctx.device }}. Lua and JavaScript read value or ctx.device. A Run if condition can check it, for example {{ ctx.choice == 'yes' }}.
The opener gets the value only once, when the screen closes. To update something while the screen is still open, write to app variables instead and read them as vars.my_key. See Runtime vars.
Examples
Device picker. A bottom sheet Devices lists your devices. Each item has one tap action: Close screen with Result {{ value }}. The button that opens the sheet has these tap actions:
- Open bottom sheet → Devices, Apply result → ctx key
device, If closed without a result → Stop actions. - MQTT send to the topic
devices/{{ ctx.device }}/cmd.
If you close the sheet without picking a device, nothing is sent.
Form. A screen has a text field nameField, a slider tempSlider, and an OK button with these tap actions:
-
Lua:
ctx.result = { name = components.nameField.value, temp = components.tempSlider.value } -
Close screen with Result
{{ ctx.result }}.
The opener gets an object, not text, so the next actions can use {{ value.name }} and {{ value.temp }}.
Live form. A sheet has sliders and no OK button. Each slider's On changed actions pipe has Set screen result with Result {{ value }}. You move a slider and swipe the sheet away. The opener still gets the last value.
On open and On close
A screen can run actions on its own when it opens and when it closes. Use them to connect to a device only while the screen is open, to send a "screen shown" message, or to set the value the screen returns.
In the designer, tap an empty spot so nothing is selected. Open Events, then tap On open or On close. They work like other action lists: the switch turns the list on or off, and a tap on the row opens its actions.
When they run
- On open runs once each time the screen opens.
- On close runs once when the screen closes, however it closes: Back, Close screen, or a screen below it closing.
- Opening another screen on top is not closing. On close waits until this screen itself closes.
- They don't run while you design the layout.
- If the system stops the app or you force-quit it, On close doesn't run.
- On close can't keep the screen open. The screen closes anyway, even if an action fails.
In these actions, params holds the screen parameters and value is the current value of the screen's data source.
Which actions you can add. All Data actions except Apply value and Debounce, plus Set screen result. Other UI actions — opening a screen, asking a question, showing a message — are not offered: while the screen is sliding in or going away, there is no good place to show them. To open another screen, use a tap on a component.
Examples
- Connect while open. On open: Connect for the room's MQTT connection. On close: Disconnect for the same connection.
- Default result. On open: Set screen result with Result
cancel. An OK button has Close screen with Resultok. If you leave with Back, the opener getscancel. - Result on close. A sheet has sliders and no OK button. On close has a Lua action,
ctx.result = { temp = components.tempSlider.value }, then Set screen result with Result{{ ctx.result }}. Swipe the sheet away and the opener still gets the slider value. The opener waits for On close to finish before it reads the result.
Custom screen vs Data piece full screen
| Custom screen | Data piece full screen | |
|---|---|---|
| What it shows | A layout you designed | The same data piece, as large as it fits |
| Pinch to zoom | No | Yes |
| Parameters | Yes (params.room) |
No |
| Reuse | Many data pieces can open the same screen | Always that one data piece |
Both are choices in the Open screen tap action. See Tap actions.
Custom screen vs Freeform section
A Freeform section on the main screen also lets you place components anywhere. The difference is when you see it: a section is always one of the pages on the main screen, and you swipe to it.
A custom screen is not on the main screen at all. It appears only when an action opens it: Open screen on a tap of a data piece or a component, on another custom screen or bottom sheet, or in any action list that runs it. Back closes it and returns you to where you were.
| Custom screen | Freeform section | |
|---|---|---|
| When you see it | On demand, when an Open screen action opens it | Always, as a page of the main screen |
| What it holds | Components and groups | Data pieces, components, and groups |
| Size | Fixed Aspect ratio, separate vertical and horizontal layouts | Scales to the screen width and scrolls when taller |
| Parameters | Yes (params.room), different for each opener |
No |
| Returns a value | Yes (Close screen or Set screen result) | No |
| On open / On close | Yes | No |
| Where you edit it | Menu → Data → Custom screens | On the main screen, with Edit layout |
Both have a root data source and Periodic action pipes. Use a Freeform section for what you want to see all the time, and a custom screen for details, controls, or a form you open only when needed.