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.

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:

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.

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

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:

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:

  1. Open bottom sheet → Devices, Apply result → ctx key device, If closed without a result → Stop actions.
  2. 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:

  1. Lua:

    ctx.result = { name = components.nameField.value, temp = components.tempSlider.value }
    
  2. 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

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

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.