A modular component library for building touchscreen smart home control panels using ESPHome + LVGL on cheap ESP32 displays.

See ARCHITECTURE.md for the full design rationale.

Each entity type lives in ui/<type>/ and provides:

ui/<type>/local.yaml    — tile for an ESPHome component on the same device
ui/<type>/remote.yaml   — tile for a Home Assistant entity
ui/<type>/detail.yaml   — full-screen detail page (complex types only)

Your device YAML composes a panel by including one hardware file, the shared infrastructure, and one !include per tile. Everything internal (globals, scripts, detail page) is wired automatically.

ESPHome 2026.7.0 or later (the image: component uses the new platform: file form introduced in 2026.7.0). For SVG image support (required by solar/tides modules):

pip install cairosvg

cd /config   # or wherever your ESPHome configs live
git clone https://github.com/agillis/esphome-modular-lvgl-buttons.git

Create secrets.yaml in your ESPHome config root (one level above this repo):

wifi_ssid: "your-ssid"
wifi_password: "your-wifi-password"
ap_password: "your-fallback-ap-password"
latitude: 0.0000
longitude: 0.0000

Copy the closest example from example_code/ and adapt it, or start from scratch:

esphome run my-panel.yaml

Click any type name in the table above for its full variable reference and usage examples.

Pages use LVGL's grid layout. layout: NxM creates N rows × M columns.

Tiles are placed with row and column (0-based). Use row_span / column_span to make a tile span multiple cells.

Add more pages to the lvgl.pages list, include swipe_navigation.yaml on each, and set page_id on tiles to route them to the right page:

lvgl:
  pages:
  - id: main_page
    layout: 3x3
    styles: page_style
    <<: !include esphome-modular-lvgl-buttons/common/swipe_navigation.yaml
  - id: lights_page
    layout: 2x3
    styles: page_style
    <<: !include esphome-modular-lvgl-buttons/common/swipe_navigation.yaml

Icons use Material Design Icons via substitution variables. Usage: icon: $mdi_lightbulb.

The icon name must also be listed as a glyph in your device font: block — otherwise it will render as a blank square:

font:
- file: 'https://github.com/Templarian/MaterialDesign-Webfont/raw/v7.4.47/fonts/materialdesignicons-webfont.ttf'
  id: mdi_icons_40
  size: 40
  bpp: 8
  glyphs:
  - $mdi_lightbulb
  - $mdi_ceiling_light
  - $mdi_thermostat
  # ... add every icon you use

Each detail page type also requires specific glyphs — see the type's README.md.

The theme lives in common/theme/ and is a self-contained bundle — one include pulls in colors, fonts, MDI glyph substitutions, and LVGL styles. See the theme README for the full color palette, font sizes, and customization reference.

The common/theme/index.yaml bundle includes colors, fonts, MDI glyph substitutions, and LVGL styles in one include.

To debug layout, swap to the debug variant which adds red outlines to all widgets:

# theme: !include esphome-modular-lvgl-buttons/common/theme/index.yaml
  theme: !include esphome-modular-lvgl-buttons/common/theme/index_debug.yaml

Theme appearance is controlled via substitution variables:

Available named colors: ep_orange, ep_blue, ep_green, steel_blue, misty_blue, very_dark_gray, gray800, gray900, and all standard CSS colors.

Test your UI on macOS or Linux without flashing hardware:

# macOS
brew install sdl2

# Ubuntu/Debian
sudo apt install libsdl2-dev

Use the SDL hardware config instead of a real device:

packages:
  hardware: !include esphome-modular-lvgl-buttons/hardware/SDL-lvgl.yaml
  sensors:  !include esphome-modular-lvgl-buttons/common/sensors_base_sdl.yaml

Then esphome run your-config.yaml — a window opens simulating the display. See example_code/SDL-lvgl-display_modular_480px.yaml for a full working SDL config.

One hardware file per display, in hardware/. Include the one matching your device (hardware: !include esphome-modular-lvgl-buttons/hardware/<model>.yaml). The Driver column is the ESPHome display platform each file uses.

hardware/generic.yaml is a starting template for boards not listed above. Audio/voice add-ons (include alongside a screen, not standalone): hardware/media_player-voice_assistant.yaml and hardware/guition-esp32-jc4827w543-audio.yaml.

Additional UI modules under ui/ for specific integrations:

See example_code/advanced/ for full working configs using these modules.

MIT — see LICENSE.