zigbee2mqtt-windfront (new frontend)

[Koenkk]

2025-09-01: Discussion locked, let's continue in #28442

---

Feel free to give feedback on the new experimental frontend called zigbee2mqtt-windfront here! This new frontend is an improved version of the current frontend developed by @Nerivec.

To enable this new frontend set the following in your configuration.yaml (the Zigbee2MQTT one, not the one from Home Assistant!):

frontend:
  enabled: true
  package: zigbee2mqtt-windfront

To revert back to the original frontend, simply remove the package line, or set it to package: zigbee2mqtt-frontend (the default) and restart Zigbee2MQTT.

Tip

You can also update this setting from any frontend, in Settings page, after updating to Zigbee2MQTT 2.4.0 or above.

Important

Make sure you restart Zigbee2MQTT after changing this configuration. If you use Home Assistant, Zigbee2MQTT itself must be restarted, not Home Assistant.

Tip

You can use WindFront as standalone (in its own Docker or other setup type): https://github.com/Nerivec/zigbee2mqtt-windfront/wiki#standalone-serving-with-multi-zigbee2mqtt-support

Issues: https://github.com/Nerivec/zigbee2mqtt-windfront/issues
Discussions: https://github.com/Nerivec/zigbee2mqtt-windfront/discussions

Developers discussion on network map: Nerivec/zigbee2mqtt-windfront#29

[MBRetrofit]

Indeed, it's too political woke

[raveit65]

What does these colors have to do with "political woke"?

[Plobli]

The shadows on the buttons look very outdated and obscure the structure of the buttons.

[bartkummel]

The new graph is unusable indeed. I liked the old one more. Wasn't perfect either, but way more usable than this one.

[asveikau]

I don't see the "Display type: map" at all, and I see a download button rather than a refresh icon. Tried it on a few different browsers (Firefox and Chromium on FreeBSD, then Android phone with chrome) in case it's a client side issue. So for me there is no builtin map viewer, I can only get the textual representation and paste it somewhere else.

Edit: OK, I got it, if I select "raw", generate it, I can then switch to map. It is in fact working here. But this is a very non-intuitive, non-discoverable UI that took too many clicks to get to something that used to be more simple and self explanatory.

[nesalkiN]

I don't see the "Display type: map" at all, and I see a download button rather than a refresh icon. Tried it on a few different browsers (Firefox and Chromium on FreeBSD, then Android phone with chrome) in case it's a client side issue. So for me there is no builtin map viewer, I can only get the textual representation and paste it somewhere else.

You click the "download" button when you have raw selected. When done another dropdown should appear where you can switch to map.

[Tommixoft]

Yeah me too... all seems to be good (well dashboard is a mess but i dont use it) exept the MAP... there is no option for normal one... looks like they pack more info but representation is not nice. Old one was really better.
But still i see nothing to make me switch to new UI. Not to offend anyone. Just there is no added value in new UI.

[Nerivec]

The main goal of WindFront was to bring everything up to date, and optimize the "behind the scene" code base. The original frontend has some outdated libraries that would be rather complicated to update without risking the introduction of new issues. Overall, the re-design of the UI was only a small part, albeit the one "seen" by most; very subjective area too, so, a base was built, and now we're adjusting based on feedback 😉. The ability to switch frontend allows to keep the original and introduce new ones, users can pick whichever they prefer, and give feedback without having to permanently commit.

A lot has already changed in WindFront thanks to quite a lot of feedback! You can check the release notes https://github.com/Nerivec/zigbee2mqtt-windfront/releases for more details (everything after v1.0.2 is currently available in Zigbee2MQTT dev branch / edge addon). New features will come once a stable base has been established! 🪄

[Jannify]

You can also change it in the (old) settings ui of z2m. Changing the config file manually didn't work for me.

[MSL-DA]

After a restart via "addon" in HA, it changed to the new one, unclear why. HA restart did not work.

HA restart does not restart Z2M. Old news ...

[array81]

Same thing for me, I add the line to the configuration file, restart but the old interface is loaded and also the configuration file is modified: the line added shortly before is removed.

[z-master42]

You have to add it to the addon's configuration.yaml and restart the addon.

[array81]

I added the line in Zigbee2Mqtt configuration.yaml file then restarted it. But I get the old interface.

[errormastern]

"Show all" would be great for those who doesn't want to have a pagination like me

[jkufner]

Do we need the pagination at all? Zigbee networks are not that big and a thousand rows in a table is fine.

[MSL-DA]

Thanks for that. I appreciate the effort, but the color contrast feels a bit too strong and gives it a somewhat outdated, '90s-style appearance 🫢

[KoalaWerewolf]

Second the "Show All".

[GTunney]

Couldn't agree more, I've went back to the old interface for now.

The way the information was displayed on the old dashboard was way more effective than the new one.

[Plobli]

Yes. To me, the new design looks like a search for effect. As if colorfulness were more important than efficiency. I find it inefficient. My eye doesn't know where something begins and where it ends. It lacks structure and form. It's a big mess.

Take the dashboard, for example: I miss frames around things that belong together. There are too many brightly colored buttons, and with some of them it's not immediately clear what their function is.

[MBRetrofit]

Choose Type Raw, Enable Routes, Display Type Map press refresh

[nesalkiN]

It tells you what to do. It has generated your map but you need to paste that text in to external tools that will render the map. To see the map you need to select raw and map.

[jkufner]

Then the raw should be the default. It is nice to have an export, but the default really should be to simply show something.

[francisp2]

Only if you use the add-on. For me it is /opt/zigbee2mqtt/data/configuration.yaml

[hemertje]

made the same mistake in the HA config ;)

added the lines to /homeassistant/zigbee2mqtt/configuration.yaml

now i have the error

Zigbee2MQTT
The add-on is not running. Do you want to start it now?

[hemertje]

there is allready in the /homeassistant/zigbee2mqtt/configuration.yaml

frontend:
  enabled: true
  port: 8099

I made:

frontend:
  enabled: true
  package: zigbee2mqtt-windfront
  port: 8099

the result:
502: Bad Gateway

[hemertje]

After a restart of the Zigbee2MQTT Add-On it is working!

[Trebor87]

@Koenkk I had the same error. The documentation should clarify that the /homeassistant/zigbee2mqtt/configuration.yaml is the one, which should be edited.

Nicely spotted, Many thanks :)

[ciddi89]

Yes I have the same issue on Safari and Firefox.

[carlhye]

Came to find this information.

[DataLohr]

thanks, never notices, that someone could mean another one.

[Nerivec]

Pagination was removed in 1.0.3, so it's always show all 😉
https://github.com/Nerivec/zigbee2mqtt-windfront/releases

[PaulBiod]

Hi,
I've read that switching from old UI to this new UI could make some devices change their name. Is it true ?
Thanks

[Nerivec]

I'd have to say no (name is sent by Z2M, and only changed if requested by user), but maybe someone found a bug (display issues, etc.) or something got misunderstood.
Can you point me to where you read that?

[PaulBiod]

Hi, thanks for your reply. I've seen it in the AI results of google. But I can't reproduce it

[sdotter]

Niceeeee new frontend! Really impressive update! thanks

[Nerivec]

The colors are purely theme-driven (no customization in that regard). The defaults (light/dark) have highly contrasting colors, but a lot of other don't.

We can however do this in all the tables and in the dashboard (all places where lots of buttons are present)

[SergioFuchs]

Nice job new UI
It would be good if there was a way to filter by availability, then I could see the devices that are having problems to solve.
Thanks

[Nerivec]

If you click on the "Availability" heading of the table, you will sort the column, and all "offline" will show first (clicking again will cycle sorting order).

[pxFIN]

Very nice improvements!

A couple of questions..

1. Can network map background be changed in the future ? It seems to be now always white.. on screen and on exported picture
2. Websocket Open status.. clicking it shows only part of the wss url + part of the url theres a purplish color block ? Is the info broken ?

[Nerivec]

1. I'll check what we can do about that. This is a separate rendering, so theming is a bit trickier 😉
2. Will be fixed in next version (the box is failing to adapt if the text is too long). Note that this is primarily meant for standalone, multi-Zigbee2MQTT support, to switch instances: https://github.com/Nerivec/zigbee2mqtt-windfront/wiki#standalone-serving-with-multi-zigbee2mqtt-support

[Nerivec]

1. Should be fixed in 1.3.0, will adapt to current theme (will be available in Z2M August release, or in dev branch soon).
2. Should be fixed in 1.2.1 (Z2M July release).

[francisp2]

Does not work very well on Firefox 115.25..0esr

[Nerivec]

Looks like something is preventing the design library from properly loading. Adblocker blocking something it shouldn't, or something similar? Or maybe the installation got corrupted and is missing files?

Also, ESR 115 is pretty limited in support (legacy), so, even if you fix that, I would expect some things to not work properly (feature-set is old). ESR 128 should be better (still pretty far behind regular Firefox, but at least the feature-set is more recent).

[francisp2]

Yes, Firefox says 'is up to date', but it is indeed a really old version. On the other PC with Firefox Windows 140.0.2 no problems

[Merril-r]

@Nerivec

Could you look at the following:

• There are no names for the child devices on the map. I only see names for the main powered devcies.

• When adding new devices I only see all. Does not allow me to select a powered device to add a child to it

• Not sure how you determine which colour is used on the LQI strength.

  It would be nice if you could make a good signal strength green instead of red. Red makes me think of an issue.

  Use red for low LQI, green for good LQI and the current (thats how it displays by me) orange for intermediate quality

[Nerivec]

1. The rendering library used has a couple of issues at the moment. This is one of them. See the Legend above the map, there is a workaround given. I'll try to spare some time to contribute there to fix this!
2. You mean you don't see a list of routers if you click on the arrow next to the permit join button? If so, please open an issue with a more detailed description/screenshot/short video.
3. Red is very low (less then 75), orange is low (less than 125), green is high (above 200), in-between 125-200 has no color. It's based on the 0 (lowest) 255 (highest) range that LQI can have. Note: due to the differences in radio & firmware (and of course your environment), you may see more or less red/orange/green, LQI calculation is internal to each adapter firmware.

[Merril-r]

@Nerivec
Old age and blindness creeping in. I never saw that arrow. I cant see the list now. Thanks

thanks for the explanation on the colours for LQI. I see even my devices that are 3m away from my zigbee co-ordinator are only 175. Not sure how many people have a value of more than 200. Would be nice if it could be dropped. But it would depend on the request for that. Perhaps something to ask in the forum.

Thanks for sparing some time to look at the rendering issue.

[nesalkiN]

Not sure how many people have a value of more than 200

I have 46 devices. 23 end devices and 23 that routes. 13 show over 200. :)

[Merril-r]

What devices are these and what co-ordinator are you using?

[nesalkiN]

What devices are these and what co-ordinator are you using?

The ones showing over 200? Light bulbs, plugs, fire detector, temp/hum-sensors, wall switch. Mostly powered/routing devices (plugs and lights).
Sonoff ZBDongle-E. No devices showing red or yellow.

[knuti1960]

I really like Windfront now and use it all the time.

Not only does it look great (dark mode for me), but it also offers a lot of things that weren't available in the previous frontend.
The many new options for displaying the network are also fantastic. I'm still getting my head around it and need to get used to it, but the possibilities are apparently huge.

A layman can hardly estimate how much work is involved, but it must be a lot!
Thank you very much!

[Nerivec]

See my reply to your original post above 😉

[pxFIN]

Health reset its always restart of container or.. ?

I wonder button of i am not sure of

[pxFIN]

Most likely leave it as it is.. its quite difficult to determine

[Nerivec]

Yes, it is "whole-runtime", unless you use the option to reset after every check.
This is not specific to WindFront though, it's Z2M settings.
Of course, several of the stats are "instant"/"permanent" (like os, process), these are never "reset" (simply doesn't apply).

[pxFIN]

Change the white back ground of network

Otherwise I just love it

I cant even find anything whats the problem after that

[pxFIN]

@Nerivec I know people say always improvements

I appreciate what you do

And to this day i see perfect improvement

Thank you!

[Nerivec]

Change the white back ground of network

As mentioned this will be fixed in next version.

Thanks for the feedback and the support 😉

[cadavre]

Do you plan to leave and maintain also current (pre-windfront) frontend?

[Nerivec]

There is no plan to remove support for the original frontend at this time. It however receives mostly maintenance fixes (has for a while now).

[VincentSC]

There is a newly introduced bug in the current frontend, and the solution was "switch". As the default setting for "last seen" is disabled by default on Home Assistant, the bug causes a lot of noise on https://github.com/nurikk/zigbee2mqtt-frontend/issues

It would be good to have the option to switch in the Home Assistant Addon, without having to edit the configuration.yaml. Preferrably as default.

[h0m3d0m0]

10 sec and revert back to the old frontend
Keep it clean and simple like the original front (y)

[0rsa]

Having many instances centralized in one UI is a must have, thanks for that.
I also like the look'n'feel which is a bit more polished than the original UI.

What I dislike :

• Heavy feeling: devices loadings are blocking the UI and make it unresponsive during some time
• Firmwares versions numbers in hexadecimal format, I prefer the old UI numbers format

What I would like to have :

• A filter in the dashboard to filter the devices which are on a "on" state