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.

Supported Controllers

The current UiFlow2 firmware enables both LVGL and M5UI on the following 9 controllers:

  • Core2 (M5STACK_Core2)

  • CoreS3 (M5STACK_CoreS3)

  • M5Dial (M5STACK_Dial)

  • StackChan (M5STACK_StackChan)

  • StopWatch (M5STACK_StopWatch)

  • Tab5 (M5STACK_Tab5)

  • Tab5X (M5STACK_Tab5X; inherits the Tab5 LVGL and M5UI configuration)

  • Tough (M5STACK_Tough)

  • ToughC5 (M5STACK_ToughC5)

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.

  • Recommendation: For new interactive UI projects, prefer M5UI/LVGL. Use M5.Widgets for simple or legacy UI components.

3. M5UI

  • A high-level UI framework based on LVGL.

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

  • Recommendation: Prefer M5UI/LVGL for new interactive UI projects.

  • 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/LVGL (recommended for new projects).

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.

Most firmware builds with CJK font support also expose these 24 px LVGL font objects for m5ui widgets:

  • lv.AlibabaPuHuiTi_CN24 - Simplified Chinese

  • lv.AlibabaSans_JP24 - Japanese

  • lv.AlibabaSans_KR24 - Korean

The LVGL and M5.Lcd.FONTS object names are different. Use the spelling shown for the UI API you are using.

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

Important

Check the target controller’s documentation for its supported fonts before selecting a font. If the documentation does not provide this information, check availability at runtime, for example with hasattr(lv, "font_montserrat_20").

Font Selection Guide:

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

  • m5ui widgets with CJK text -> lv.Alibaba*24

  • 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