Building Pages in the OH3 UI: documentation draft (1/3)

UPDATE: The most current information on this topic is now available at: User Interface Design Overview | openHAB. The following is kept for archival purposes only!


I. Pages basics (this topic)

  1. Concepts: UI components, pages & widgets
  2. Sitemaps
  3. Types of pages
  4. Page editors, creating a page & adding widgets

II. Editing pages & widgets: general information

  1. Configuring widgets
  2. The system & standard libraries, default widgets (standalone, list items & cells), adding widgets from the model
  3. Widget actions
  4. Expressions
  5. Personal widgets: development & usage

III. Building specific types of pages

  1. Layout pages
  2. Floor plans & maps
  3. Chart pages
  4. Tabbed pages

Concepts: UI components, pages & widgets

In openHAB 3 Pages there is a concept of “UI components”. UI Components can be created using the UI and they can be viewed and edited in YAML from the Code tab. There are a number of component types for showing information and interacting with your Items including toggles, knobs, sliders, text entry, date and time pickers, etc. These components can often be combined to form a composite component for advanced displays (e.g. a weather widget showing current conditions and the forecast and access to your thermostat settings).

UI Components are presented on Pages. There are a number of different Page types.

Types of Pages

  • Layout pages: Allows you to organize/layout multiple widgets on the same page in many ways. The below screenshot shows only some of the different types of UI components that are available.

  • Floor plans & maps: Allows you to put markers over the top of a background layer that you can zoom & pan. You can use your own picture (like the example showing a floor plan), or a map of the world;

  • Chart pages: A page based on the powerful Apache ECharts to visualize historical data:

  • Tabbed Pages: Use to group several pages that are selectable between them with tabs on the bottom:

Construction of a UI Component

As mentioned, a UI Component can be inserted and configured through the Page builder interface (Settings -> Pages). For advanced configuration, sharing with others, and advanced configuration a YAML representation of the component can be viewed in the Code tab of the UI Component editor.

For example:

component: oh-type
  prop1: value1
  prop2: value2
  prop3: =expression
    - component: ...
      config: ...
      slots: ...
    - component: ...
    - component: ...

This is a little bit technical but you’ll encounter these YAML structures pretty often when you start doing advanced things, as the various editors in the UI have menus everywhere to edit the YAML of a component directly.

Each component has a type, configuration properties which can be made dynamic with expressions (not always though, more on that later), and optional slots which hold more components. Slots are optional, and have a name; usually when there’s slots involved there’s a default slot but it’s not guaranteed. The semantics of both the config properties and the slots depend on the component type, as well as the allowed sub-component types in the slots.

At the top of the tree there’s a root component which has additional attributes:

uid: component1
    - name: group1
      label: Property group
   - name: prop1
     label: Prop 1
     type: BOOLEAN
     groupName: group1
     description: What prop1 does
   - name: prop2
     label: Prop 2
     type: TEXT
     context: item
     description: Choose an item for this prop
   - name: prop3
     type: NUMBER
     advanced: true
tags: ["tag1", "tag2"]
component: ...
config: ...
slots: ...

The root component has an uid (it’s Unique IDentifier), a props structure describing its own properties (when we reuse a component in another one, for instance a personal widget on a page, this will help in building a user-friendly configuration sheet to set up the widget; the props parameters and descriptions adopt the structure of the configuration descriptions found in bindings, services and throughout openHAB:

[ RLK I propose striking the following paragraph and reintroduce it later when/if it’s needed. A new user (or even myself) doesn’t know what any of this means or why I need to know it. ]
Root components are stored in namespaces; for instance, the pages are stored in the ui:page namespace, the personal widgets in ui:widget, HABPanel uses UI components to store its panel configurations and dashboards, and UI-managed sitemaps are stored in the system:sitemap namespace. The component types valid in a specific namespace vary.


Sitemaps are an efficient way of organizing and displaying Items. There are many dedicated clients able to render them: Basic UI, the mobile apps, the Windows app, Pebble and others.

Unfortunately, the main UI, cannot render them. However, it can store “managed” sitemaps and if properly formatted, they will appear in clients as uicomponents_{uid}. Note that this doesn’t prevent writing them in files with the dedicated syntax - they simply won’t be listed in the main UI or be editable through the UI.

Page editors, creating a page and adding widgets

To manage pages, first login as an admin, then from the sidebar, under Administration in the sidebar, go to Settings then Pages. The list of pages (and managed sitemaps) will appear. You can group name alphabetically or by type. Click on a page in the list to edit it or use the ‘+’ button in the lower-right corner and choose the type of page you wish to create:


Note that you likely already have a page named “Overview” (uid: overview) represented by a home icon. This page is a special one, it’s created by default and it cannot be removed. The contents of this page will be displayed on the Overview tab of the home page. This overview page includes several tabs which will display Items that are part of your semantic model in various ways including:

To delete pages, use the Select link in the upper-right corner and check the pages that you want to delete, then click the Delete button (the appearance will differ depending on the current theme).

The look & feel of the page editor will be quite different depending on the type of page that’s being edited, but they will feature more or less the same elements (except the sitemap editor).


The Design and Code tabs allow to switch from a visual editor to a YAML representation of the page

If you’re on a desktop, you can use Ctrl-S (or Cmd-S on Macs) to save the page quicker. Currently, you’ll be taken back to the pages list when you save with Ctrl-S if it’s never been saved before (i.e. you’re creating it), afterwards you will stay in the editor. When you click/tap on the Save button, however, you will always go back. Also, if you create, update or delete a page, the change is only detected detected in the current instance of the UI, on the other ones you’ll have to refresh the page with browser to reload (if you don’t have a refresh button go to Help & About and click on Reload the app).

In the Design tab, you’ll find a header with some general settings about the page:

  • its UID (that can can only set once, during the page creation, after that you cannot change it);
  • the label;
  • an additional collapsible section with:
    • “visible only to”: allows to select the user role(s) you want the page to be visible to; if none are specified the page is visible to unauthenticated visitors as well;
    • “Show on sidebar” : allows to control whether or not the page appears in the sidebar menu on the left - indeed, it’s not necessary to display all pages in it; using widget actions (see below), you can display other pages (standard navigation or in modals like popups etc.), thus creating hierarchies of pages is possible, the sidebar menu being the entry pages to these hierarchies. You may also choose to hide pages from view until they’re ready.
    • “Sidebar order”: allows to reorder the sidebar menu, choose an integer for each page on the sidebar, the lower values will make the page higher in the menu.

Do not be fooled into assuming the “visible only to” feature gives you any security, it’s only a way to restrict the visibility; it can be enough for non tech-savvy users but there are many ways to circumvent this restriction and talk to your items anyways.

Some editors also feature a “Run mode” switch in the bottom toolbar:


With this switch you can preview how the page would look when viewed outside the editor, to go back & forth quickly between the design interface (or code view) and the run mode, you can also use Ctrl-R on a desktop (Cmd-R on Macs).

Now that we have a basic understanding of what Pages are and how to manage them, let’s see how to build one step-by-step.


I’m making a few changes. Feel free to reverse any of them.

I think we should avoid too much comparison of OH 3 to OH 2 in the core documents like these. There will be a growing number of users whose first exposure to OH is going to be through OH 3 and calling back to OH 2 to help explain core concepts may add to their confusion rather than add clarity. I would hope that those who are proficient in OH 2 would recognize when there are similarities or minor differences.

We could also create a migration tutorial again and centralize all those subtle differences in one place that a new user to OH 3 would never look at.

The changes I’ve made above reflect this idea.


By all means, yes! :astonished:
I was just re-reading myself and realized I might have needed an additional coffee or two before writing this thing this morning :wink:

It’s always hardest to write the first draft. It’s a good document. I’ve inserted a couple of notes/comments above inline.

Mainly, I’m not sure how to put it all together in the first section. Maybe a comprehensive example would help showing a UI with a bunch of elements and the YAML that generates it would help.

I’ve a question at the end of section 2 regarding what you meant by “does not have access to the file”. If I understand correctly maybe it would be more clear to write the sentence as

Note that this doesn’t prevent writing them in files with the dedicated syntax [add link to sitemap docs] but any sitemap defined in a .sitemap file will note appear in the main UI and can only be edited through changes to the .sitemap file itself.

1 Like

I understand, as mentioned it’s a overall view of the general concept which is all-important for what’s coming - all this is allowed because of a generic API is now available for UIs to store their stuff, really. And since that component structure will be encountered everywhere when editing page-related things in “code view” I thought it might be valuable to describe it first - maybe at the risk of putting off some users, that could be an issue for sure, I agree.

Yes indeed, in openHAB there are “sitemap providers”, there was the one which provided a thing-oriented “_default” sitemap in OH2; this one has been removed AFAIK, but there’s still the provider parsing .sitemap files and now there’s the “managed” UI components one. The resulting set from all sitemap providers is fed to the clients as one unified set; but a sitemap from one provider can’t be changed by another provider, in other words, you cannot change your file-based sitemaps from the UI, or the other way around (unless you edit the JSON DB).

Will the new UI concept be reflected in the Android app?

Not with native controls, but I’m sure the Android app will be able to show the UI (like it does with HABPanel) eventually. It works good enough as a web app, and you can already add it to the home screen and run it fullscreen.

Hi guys

Its possible to build a widget with subsequent that shows other info like the one I built in habpanel

And furthermore its possible to change the command that rollershutter widget send?
The widget send the command DOWN , I want send command close instead

Thanks in avdance

This seems quite similar to so with some styling I think this could be possible.

The rollershutter control is little more than segmented buttons but tailored to control a standard Rollershutter item, if you have a different situation it’s likely possible to reproduce its functionality in a custom widget using f7-segmented and f7-button with your specific commands.

Thanks for the answer Yannick Schaus

Other info concerning standard openhab widget,

What string i should insert into icon fileds if i want to use icon in icon/classic folder?

The same for floorplan images, it works if I put an external url, but if I insert localhost/image.png it doesn’t show nothing (standard missing image icon)
What is the url for local file?

And how to show different color for icon based on item values? The example in expression doesn’t work in standard widgets

Thanks again for your support

@livio You should be able to access local icons (…/openhab/icons/classic/) by using the ‘oh-icon’ component with the config parameter ‘icon: YOURICON’.

There is currently no option to change the icon color (for local icons) with styling params like ‘color:’ AFAIK (at least, not for the oh-icon component) - I think it has something to do with the fact that icons gets imported as images and not as a font (like the f7-icons do).
But you could use ‘filter:’ as a style to trick a bit (with good support for the most browsers)

Here is a great Codepen, which should help you, finding the correct filters to apply to set your desired color.

For example, setting your icon color to red (#ff0000):

filter: invert(14%) sepia(99%) saturate(7416%) hue-rotate(0deg) brightness(94%) contrast(114%)

To show/hide the respective icon based on the item state it should be possible to do that with the visible param… e.g.: ‘visible: =items[props.item].state === “OFF”’

To show a local image for e.g. a floorplan use the - its respective folder would be ‘…/openhab/html/floorplan.png’.

Hope it helps.

This Is clear that the new UI does not allow editing an existing sitemap. But does it at least allow rendering such a sitemap so that we can control our home in the new main UI as before without a full redesign?
Of course, we have still the old UIs and this will not not be a full break even if control of existing sitemap not possible in the new main UI could be very deceiving for most of users in a first time.

At least the information should be absolutely clear in the documentation.

I have not found how to control my home with my sitemap in the new UI when I tried OH3.

1 Like

You can install BasicUI and reuse your existing sitrmap. What is unclear ?

1 Like

If you mean an existing sitemap file, the UIs have never done that. OH assumes if you use files you edit the files yourself with your favorite editor.

Basic UI is there for using sitemaps. The new UI does not use the old sitemaps.

If true, this is exactly the information I would like be mentioned clearly in the documentation.

I assume I will not be the only one to ask myself this question.

1 Like

You mean like this?

Please re-read before posting. It is clearly stated in plain English. I just added emphasis above.

1 Like

The “(yet?)” is very confusing. Does it mean this is not yet finished but it is in the pipeline ?

That means it does not work NOW.

To me “(yet?)” means they have not yet decides whether it will ever work but it may ne a remote possibility.

Either way we are talking here about current behavior and it is clear on that point.