M5UI

M5UI is a UI library based on LVGL v9.3. It provides a set of widgets and functions to create user interfaces for M5Stack devices.

It has been adapted for M5Stack devices and you only need to call m5ui.init() to start using it.

M5 Series Display Libraries

1. Display (M5.Lcd)

  • A low-level graphics library providing basic screen drawing, text, lines, and color management.

  • Can be used independently, suitable for scenarios that only require drawing graphics or text.

  • Access via: M5.Lcd.fillRect(), M5.Lcd.drawRect(), M5.Lcd.drawString(), etc.

2. Widgets (M5.Widgets)

  • A basic UI widget library providing labels, image displays, and other UI controls.

  • Built on top of M5GFX.

  • Suitable for simple interactive UI elements.

  • Access via: M5.Widgets.Label(), M5.Widgets.Image(), M5.Widgets.Rectangle(), etc.

  • Important: M5.Widgets provides UI component classes, not drawing methods.

3. M5UI

  • A high-level UI framework based on LVGL.

  • Provides page management, multi-widget layouts, and unified event handling.

  • Access via: m5ui.M5Label(), m5ui.M5Button(), m5ui.M5Page(), etc.

Usage Tips

  • ⚠️ Do not mix M5GFX, M5Widgets, and M5UI simultaneously, as it may cause rendering issues or event conflicts.

  • For graphics-only drawing → use M5GFX (M5.Lcd).

  • For simple interactive widgets → use M5Widgets.

  • For multi-page UI → use M5UI.

Common Mistakes to Avoid

  • ❌ WRONG: Widgets.fillRect() or Widgets.drawRect() - These methods do not exist in Widgets module

  • ✅ CORRECT: M5.Lcd.fillRect() or M5.Lcd.drawRect() - Use M5.Lcd for drawing methods

  • ❌ WRONG: Mixing M5.Widgets.Rectangle() with m5ui.M5Page() - Different UI systems, don’t mix

  • ✅ CORRECT: Use either M5.Widgets OR m5ui consistently, not both together

Key Distinction: - M5.Lcd = Drawing methods (fillRect, drawRect, drawCircle, drawString, etc.) - M5.Widgets = Simple UI component classes (Label, Image, Rectangle, Circle, etc.) - m5ui = LVGL-based UI framework (M5Label, M5Button, M5Page, M5Chart, etc.)

Available Fonts

Font availability depends on the board firmware build and the UI API you use.

LVGL / m5ui widget fonts

For m5ui widgets, use LVGL font objects such as lv.font_montserrat_*. Most M5Stack firmware builds include these Montserrat fonts:

  • lv.font_montserrat_12 - Extra small text

  • lv.font_montserrat_14 - Default font

  • lv.font_montserrat_16 - Medium text

  • lv.font_montserrat_18 - Medium-large text

  • lv.font_montserrat_24 - Large text

  • lv.font_montserrat_40 - Extra-large text

  • lv.font_montserrat_44 - Extra-large text

  • lv.font_montserrat_48 - Extra-large text

Some builds, such as Tab5, also include lv.font_montserrat_20, lv.font_montserrat_22, lv.font_montserrat_30, and lv.font_montserrat_36.

M5.Lcd / Widgets CJK fonts

For drawing text with M5.Lcd or widgets based on M5.Widgets, use M5.Lcd.FONTS. Most firmware builds also include these 24 px CJK fonts:

  • M5.Lcd.FONTS.AlibabaPuHuiTiCN24 - Simplified Chinese

  • M5.Lcd.FONTS.AlibabaSansJA24 - Japanese

  • M5.Lcd.FONTS.AlibabaSansKR24 - Korean

The older EFontCN24, EFontJA24, and EFontKR24 names are deprecated aliases; prefer the Alibaba* names above. These CJK fonts may be disabled on small-flash or resource-constrained firmware builds.

Important

Do not assume every font is available on every device. If your code may run on multiple boards, use common fonts or check availability before using an optional size/font, for example hasattr(lv, "font_montserrat_20") for LVGL fonts.

Font Selection Guide:

  • m5ui labels/buttons/dropdowns -> lv.font_montserrat_*

  • M5.Lcd.drawString() / M5.Widgets English text -> M5.Lcd.FONTS.Montserrat*

  • M5.Lcd.drawString() / M5.Widgets Chinese/Japanese/Korean text -> M5.Lcd.FONTS.Alibaba*24

Example:

import m5ui
import lvgl as lv

m5ui.init()
page0 = m5ui.M5Page(bg_c=0xFFFFFF)

title = m5ui.M5Label("Title", x=10, y=10, font=lv.font_montserrat_24, parent=page0)
label = m5ui.M5Label("Text", x=10, y=50, font=lv.font_montserrat_14, parent=page0)

optional_font = lv.font_montserrat_20 if hasattr(lv, "font_montserrat_20") else lv.font_montserrat_18
value = m5ui.M5Label("123", x=10, y=80, font=optional_font, parent=page0)

Functions

m5ui.init()

Initialize the M5UI library. This function must be called before using any other M5UI functions.

Returns:

None

m5ui.deinit()

Deinitialize the M5UI library. This function should be called when you no longer need to use M5UI.

Returns:

None

Classes