How to start with pages?

A short story of my way with Openhab:

My first Openhab was Openhab1
It was easy the Classic UI/Basic UI was ok to use with an easy structure.
Only textfiles where a bit strange but it worked.

After some time I updated to Openhab 2
The Basic UI, Paper UI and the HABPanel where great to use.
Mainly configure everything from a website was great back then.

Now I am at Openhab 3
Basic UI and HABPanel are as great as they where back in Openhab 2
But these pages thing breaks my brain
It don’t know where to start or how to use.
It is so confusing and overloaded.
It’s really frustrating…
Any advice?
The instruction doesn’t do it for me.

Hope anyone can help me.

Have you followed the tutorial on the openHAB site? It is very well done and it is worth following it carefully.

A couple of years ago I was also overwhelmed by the new features of OH3 but I started slowly and kept my production system with OH2 while playing with OH3 on a test system. You can still use HABpanel and sitemaps while gradually building the new OH3 UI. The new OH3 UI offers a great deal of flexibility, starting from the simplified approach based to the “semantic model” (locations and equipment tabs ) to the customized “overview page” (overview tab ) up to highly customized layout.
In my case, I started by slightly modifying the examples for the “locations tab” in the tutorial. You can start with only one room in the semantic model and with only one equipment, playing with the items metadata to modify the appearance of the widgets that you see.

As you are coming from OH2, getting acquainted with OpenHAB3 UI pages is going to be very hard (but not impossible) using text files for configurations of things and items. OH3, in facts, can build automatically a user interface for you if you add suitable metadata information to your items, but the syntax is highly prone to spelling errors (the semantic model is a way to define metadata for your items). This is why it is recommended to use UI defined configurations so that you do not have to guess the right syntax (again, the tutorial helps you in this respect).

You say that the “instruction” doesn’t help. By that do you mean the Getting Started Tutorial or the reference docs? The people who have the most trouble are OH 2.x users who skip Getting Started, so please do go back and review that if you haven’t already.

  1. Start with defining a Semantic Model. Just create one or two locations and equipment and add some points to them to play with. Pay attention to how your changes impact the Overview page, specifically the Locations, Equipment, and Properties pages.

  2. Take one or two Items and define a “default list item widget” for them and see how that changes how the Item appears on the cards in the Locations, Equipment, and Properties pages.

  3. Dive into the properties of the Overview page and play with the settings there (background image, which badges to show, order, etc.)

Now you should have the knowledge to set up the automatically generated parts of the Overview page look how you want.

  1. Now it’s time to create a custom widget. Go through Pages - Custom Widgets | openHAB and look at the code for one or two of the simpler widgets posted to the marketplace. Experiment and look stuff up in the reference guides to learn how to create custom widgets.

You can add those widget to a Layout page (the first tab of the Overview page is a Layout page).

There are many approaches you can take overall but I follow this philosophy:

  1. Items that are used a lot get represented on the Overview layout tab.

Note most of the widgets you see there are either examples used to create the Getting Started Tutorial or they are on the marketplace.

  1. Any other Items that need to be exposed to end users of the home automation are captured in the semantic model and appear on the other three tabs of the Overview page.

That’s it. I keep it simple.


I just read every Tutorial a second time.

What I can say:

  1. I already have a complete semantic model.

When I want to control something I use the Equipment Tab. This is the best one.
I don’t have that much properties. I rarely use this Tab
The locations tab is just to much
The overview Page is the one I can’t handle. Can I just disable it?

You can edit the Overview page (when logged as an administrator, click on the orange pencil on the upper right angle of the overview page) and choose the tabs you do not want to appear (apparently the overview tab cannot be disabled in this way).

It reflects your model. If it’s too much, have a second look at your model. Not every Item needs to be nor should it be in your model. In my experience no more than 60% of your Items belong in the semantic model.

For end users, the Locations tab is the more intuitive tab to use because they just want to “turn on the lights in the kitchen”. It’s intuitive to look in the kitchen for the control to do that.

Unfortunately not, at least not yet. You can hide each of the other three.

You can just leave it empty. Nothing says that something has to go there.

There are tons of great widgets on the marketplace you can install and use.

“Can’t handle” really gives us zero insight into what specific parts of Pages you are struggling with. So ultimately we can only help with equally vague and high level responses that ultimately tell you to go look at the docs. Without direction, there is nothing we can write here that is going to be better, and likely will be significantly worse than what’s in the docs already.


I’ve tried everything read every documentation and a lot of exampes. I’ve never had such a big problem with anything about openhab. I even don’t know where to start. Pages is the worst thing ever came to openhab. It’s 100% unusable and completly confusing.

No, it is not and you can create really nice UIs with pages.
I did not read the complete old posts here, but if you can just describe what you want to achieve, we might be able to help you getting a positive experience.

Basic UI and Paper UI did their Thing in OH1 and OH2.
Main UI is not like those two not intuitive.
Sometimes less is more.

I just want to create a plan rooms->devices->Options.

Sorry, but you are comparing apples with pears.
BasicUI is still existing in openHAB 4.x and PaperUi was never meant as a daily usage control UI, but just for administration purpose.

Just try the following :

  • Add a new page (crate layout)
  • Give the page a meaningfull name
  • Enter Sidebar&Visibility and enable “Show on sidebar”
  • Press “Add Block”
  • Press “Add Row”
  • Press “Add Column”
  • Press the big plus symbol and select “Label card”
  • Press the little symbol above the new card ans select “Configure Widget”
  • Under Action select “Group Details”
  • Under “Group Popup Item” select the group of the Room you want to see
  • Enter the Room Name in the Label field.

You have created your first Page with a big "Button to show your Room like this

Easy, isn’t it :wink:

1 Like

If I could swipe from Main UI to Basic UI as the Main UI then I would do it without thinking about it. Paper UI control was a nice development from Basic UI even if it is not considered as a daily usage control UI.

I created a page in Main UI but I don’t find it.
It is only in the administration under Pages nowhere else.
Main UI and I will never get friends

That’s easy and I explained it in my last post :

After Saving, you will find it in the menu on the left


You can, in openHAB apps, you can select BasicUI as default or your browser just open




Now it looks like this:
Screenshot 2024-01-22 085146

Yes, and when you click on the equipments, you get the controls.

1 Like

And how to make it look better than this?
Screenshot 2024-01-22 093710

Depends on how you want it to look like :wink:
You can e.g. see our project „semanticHomeMenu“, which gives you s unique UI with near to zero config.
And you will find a lot of great examples how users created their overview page…
But first of all, you should have a clear imagination, what you want.

1 Like

If you use the Semantic Model (Semantic Model | openHAB) a page for rooms (i.e. locations), equipment (i.e. device types), and properties (i.e. temperatures and the like) builds itself in MainUI. You need do nothing at all. Are you avoiding the semantic model or finding something about the autogenerated Overview tabs insufficient?

The Overview page is pretty much just the logical extension of what PaperUI used to do. But it provides more capability and customization options than PaperUI used to do. But it basically serves the same purpose, only better.

  • it can show any Item, not just Items linked to Channels
  • it can present the Items in up to three different ways: Locations, Equipment, Properties
  • what is shown and how it is shown can be customized through configuration.

I don’t know about swiping. But BasicUI and sitemaps are still there like they always were. And you can access BasicUI from the icon in the top right corner. I don’t know the iOS app but I know that by default the Android app works with sitemaps, not MainUI. You actually have to go out of your way to use MainUI with the app.

It’s perfectly reasonable and acceptable to use MainUI for administration and Sitemaps for everything else.

You have lots of options.

That looks like a List Card Widget. By default, MainUI will choose a default widget to represent an Item based on the Item type and the semantic tags. The default icon (where shown) is often taken from the Item’s “Category” filed.

If these defaults are not sufficient or desired, you can define a “default list item widget” at the Item level. Navigate to the Item and click “add metadata” and choose default list Item widget". You can define a custom widget here.

If you have more than one of this type of Item, you can go to Developer Tools → UI Widgets and define a new widget there and instead of defining a new widget for each Item, just apply the widget to the Items where you want to use it.

Keep in mind that a single widget can represent more than one Item. For example:

This one widget represents both the state of the deadbolt of the front door and the openclose sensor of the front door. Clicking on the lock icon causes the deadbolt to open/close. The Icons and colors are chosen based on the states of the Items.

If you want to see how this widget works, see Door and Lock Combo. As that is a marketplace widget, you can install this widget from Add-on store → UI →
Widgets for MainUI. Even if it’s mostly what you want, you can install and modify what’s there until it’s exactly what you want.

For a simpler example, that just adjusts the icon based on the state of the Item see Temperature °F.

Be sure to look at the marketplace as there are lots of great widgets available, including the semanticHomeMenu.

Further details can be found at Pages - Item Widgets | openHAB and Pages - Custom Widgets | openHAB.

1 Like

No, it was my example from above with a label card and group popup :wink:

1 Like

I’m impressed by the design: GitHub - BangerTech/openHAB3WebUI: One of my favorite WebUI for openHAB3
But I think I’m not far enough into pages to put my items into this.

When you add a widget to a page, you have a nice form to fill in the widget properties. All you do is fill in the properties. You get the same form when you apply a custom widget to an Item in the “default list item widget”. For example:

The door widget above defines a two properties, the control item and the sensor item. This is what the “default list item widget” form looks like:

Easy peasy.

Those widgets would work the same. Each defines one or more properties. When you add it to a Page you have the opportunity to set the properties and that’s how you connect your Items to the widget.

As for the pages, you’d probably need to import the widgets first under Developer Tools → Custom Widgets and pasting the YAML from the Github page first. None of these appear to be on the marketplace. Then you’d create each page and paste the YAML for the new pages to the “code” tab for the page.

But I recommend starting smaller first. Create a simple custom widget of your own and apply it. It can be as simple as something that changes the color of an icon. Then everything in that repo will make more sense.