Display layers are meant for UI that does not belong to just one page but still needs to stay visible, such as a global background, a persistent status bar, a mask, or a floating hint.

What display layers are

In LVGL, a normal screen holds the current page. Display layers are fixed layers attached to the display itself. They stay in place when pages switch, which makes them useful for shared, persistent UI.

You can think of the stack like this:

LayerPositionBest for
BottomBelow the pageGlobal backgrounds and decorative backdrops
Normal ScreenMain page contentThe current page itself
TopAbove the pagePersistent bars, floating buttons, masks
SystemHighestUI that must always stay above everything else

Notes:

  • Use a normal screen for page-specific content.
  • Top is the right choice for most persistent overlays.
  • System should be reserved for UI that truly must stay above everything else.
  • Bottom is available only on LVGL 9.x and is best used for global backgrounds.

When to use them

Display layers are a good fit when:

  • the UI should remain visible across page switches
  • multiple pages share the same overlay
  • the content must stay fixed above or below normal pages

Avoid display layers when:

  • the content belongs to just one page
  • it should enter and leave together with the page
  • you only need front/back ordering inside a single page

A simple rule is: if it should follow a page, use a normal screen; if it should stay on the display, use a display layer.

How to use them in the editor

1. Create a screen first

In the editor, a display layer is still edited as a screen, so you can start by creating a screen as usual.

2. Assign the screen to a layer in the inspector

Select the screen, then change its Layer property in the inspector to Top, System, or Bottom on LVGL 9.x.

If a layer option is missing, the current LVGL version usually does not support it. Each display layer can map to only one screen at a time, so it works best for shared global UI rather than many separate page-like views.

3. Edit it like a normal screen

Once assigned, you still place widgets on the canvas, adjust layout, and edit styles the same way. The difference is that this content is now rendered above or below normal pages instead of being used as a regular page.

4. Verify the stacking in preview

When you switch between normal pages, layer content stays visible. During preview, check these points:

  • does it really need to persist across pages
  • does it block clickable content underneath
  • does a top-most hint cover important page content

Tips

  • Use layers sparingly: they are great for global UI, not for large amounts of page-specific content.
  • Prefer Top over System: use System only when you really need the highest priority.
  • Keep one responsibility per layer: for example, background on Bottom, shared floating UI on Top.
  • Start with a normal screen: move it to a display layer only after you are sure it should persist across pages.
  • Overview - the editor interface as a whole.
  • Navigator - creating and switching screens.
  • Inspector - editing screen properties.
  • Canvas - editing layer content on the canvas.
  • Preview - checking the final stacking behavior.