M5Dropdown

M5Dropdown is a widget that can be used to create dropdown menus in the user interface. It allows users to select one option from a list of available options with a compact dropdown interface.

UiFlow2 Example

MicroPython Example

Drop down in four directions

This example creates a drop down, up, left and right menus.

MicroPython Code Block:

 1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 2#
 3# SPDX-License-Identifier: MIT
 4
 5import os, sys, io
 6import M5
 7from M5 import *
 8import m5ui
 9import lvgl as lv
10
11
12page0 = None
13dropdown0 = None
14dropdown1 = None
15dropdown2 = None
16dropdown3 = None
17
18
19def setup():
20    global page0, dropdown0, dropdown1, dropdown2, dropdown3
21
22    M5.begin()
23    Widgets.setRotation(1)
24    m5ui.init()
25    page0 = m5ui.M5Page(bg_c=0xFFFFFF)
26    dropdown0 = m5ui.M5Dropdown(
27        x=110,
28        y=0,
29        w=100,
30        h=lv.SIZE_CONTENT,
31        options=["option1", "option2"],
32        direction=lv.DIR.BOTTOM,
33        show_selected=True,
34        font=lv.font_montserrat_14,
35        parent=page0,
36    )
37    dropdown1 = m5ui.M5Dropdown(
38        x=111,
39        y=212,
40        w=100,
41        h=lv.SIZE_CONTENT,
42        options=["option1", "option2"],
43        direction=lv.DIR.TOP,
44        show_selected=True,
45        font=lv.font_montserrat_14,
46        parent=page0,
47    )
48    dropdown2 = m5ui.M5Dropdown(
49        x=220,
50        y=106,
51        w=100,
52        h=lv.SIZE_CONTENT,
53        options=["option1", "option2"],
54        direction=lv.DIR.LEFT,
55        show_selected=True,
56        font=lv.font_montserrat_14,
57        parent=page0,
58    )
59    dropdown3 = m5ui.M5Dropdown(
60        x=0,
61        y=106,
62        w=100,
63        h=lv.SIZE_CONTENT,
64        options=["option1", "option2"],
65        direction=lv.DIR.RIGHT,
66        show_selected=True,
67        font=lv.font_montserrat_14,
68        parent=page0,
69    )
70
71    page0.screen_load()
72    dropdown0.set_selected_highlight(True)
73    dropdown1.set_selected_highlight(True)
74    dropdown2.set_selected_highlight(True)
75    dropdown3.set_selected_highlight(True)
76
77
78def loop():
79    global page0, dropdown0, dropdown1, dropdown2, dropdown3
80    M5.update()
81
82
83if __name__ == "__main__":
84    try:
85        setup()
86        while True:
87            loop()
88    except (Exception, KeyboardInterrupt) as e:
89        try:
90            m5ui.deinit()
91            from utility import print_error_msg
92
93            print_error_msg(e)
94        except ImportError:
95            print("please update to latest firmware")

Example output:

None

API

M5Dropdown

class m5ui.dropdown.M5Dropdown(*args, **kwargs)

Bases: dropdown

Create a dropdown object.

Parameters:

  • x – The x position of the dropdown.

  • y – The y position of the dropdown.

  • w – The width of the dropdown.

  • h – The height of the dropdown, default is lv.SIZE_CONTENT.

  • options (list) – A list of options to display in the dropdown.

  • direction (int) – The direction of the dropdown, can be lv.DIR.LEFT, lv.DIR.RIGHT, lv.DIR.TOP, or lv.DIR.BOTTOM.

  • show_selected (bool) – Whether to highlight the selected option, default is True.

  • font (lvgl.font_t) – The font used for the text in the dropdown, default is lv.font_montserrat_14.

  • parent – The parent object for this dropdown, default is the active screen.

set_flag(flag, value)

Set a flag on the object. If value is True, the flag is added; if False, the flag is removed.

Parameters:

  • flag (int) – The flag to set.

  • value (bool) – If True, the flag is added; if False, the flag is removed.

Returns:

None

UiFlow2 Code Block:

set_flag.png

MicroPython Code Block:

dropdown_0.set_flag(lv.obj.FLAG.HIDDEN, True)
toggle_flag(flag)

Toggle a flag on the object. If the flag is set, it is removed; if not set, it is added.

Parameters:

flag (int) – The flag to toggle.

Returns:

None

UiFlow2 Code Block:

toggle_flag.png

MicroPython Code Block:

dropdown_0.toggle_flag(lv.obj.FLAG.HIDDEN)
set_state(state, value)

Set the state of the dropdown. If value is True, the state is set; if False, the state is unset.

Parameters:

  • state (int) – The state to set.

  • value (bool) – If True, the state is set; if False, the state is unset.

Returns:

None

UiFlow2 Code Block:

set_state.png

MicroPython Code Block:

dropdown_0.set_state(lv.STATE.CHECKED, True)
toggle_state(state)

Toggle the state of the dropdown. If the state is set, it is unset; if not set, it is set.

Parameters:

state (int) – The state to toggle.

Returns:

None

UiFlow2 Code Block:

toggle_state.png

MicroPython Code Block:

dropdown_0.toggle_state(lv.STATE.CHECKED)
set_pos(x, y)

Set the position of the dropdown.

Parameters:

  • x (int) – The x-coordinate of the dropdown.

  • y (int) – The y-coordinate of the dropdown.

Returns:

None

UiFlow2 Code Block:

set_pos.png

MicroPython Code Block:

dropdown_0.set_pos(100, 100)
set_x(x)

Set the x-coordinate of the dropdown.

Parameters:

x (int) – The x-coordinate of the dropdown.

Returns:

None

UiFlow2 Code Block:

set_x.png

MicroPython Code Block:

dropdown_0.set_x(100)
set_y(y)

Set the y-coordinate of the dropdown.

Parameters:

y (int) – The y-coordinate of the dropdown.

Returns:

None

UiFlow2 Code Block:

set_y.png

MicroPython Code Block:

dropdown_0.set_y(100)
set_width(width)

Set the width of the dropdown.

Parameters:

width (int) – The width of the dropdown.

Returns:

None

UiFlow2 Code Block:

set_width.png

MicroPython Code Block:

dropdown_0.set_width(100)
get_width()

Get the width of the dropdown.

Returns:

The width of the dropdown.

Return type:

int

UiFlow2 Code Block:

get_width.png

MicroPython Code Block:

dropdown_0.get_width()
set_height(height)

Set the height of the dropdown.

Parameters:

height (int) – The height of the dropdown.

Returns:

None

UiFlow2 Code Block:

set_height.png

MicroPython Code Block:

dropdown_0.set_height(50)
get_height()

Get the height of the dropdown.

Returns:

The height of the dropdown.

Return type:

int

UiFlow2 Code Block:

get_height.png

MicroPython Code Block:

dropdown_0.get_height()
align_to(obj, align, x, y)

Align the dropdown to another object.

Parameters:

  • obj (lv.obj) – The object to align to.

  • align (int) – The alignment type.

  • x (int) – The x-offset from the aligned object.

  • y (int) – The y-offset from the aligned object.

Returns:

None

UiFlow2 Code Block:

align_to.png

MicroPython Code Block:

dropdown_0.align_to(page_0, lv.ALIGN.CENTER, 0, 0)
get_selected()

Get the index of the currently selected option.

Returns:

The index of the selected option.

Return type:

int

UiFlow2 Code Block:

get_selected.png

MicroPython Code Block:

selected_index = dropdown_0.get_selected()
set_selected_highlight(enable)

Enable or disable highlighting of the selected option.

Parameters:

enable (bool) – True to enable highlighting, False to disable.

Returns:

None

UiFlow2 Code Block:

set_selected_highlight.png

MicroPython Code Block:

dropdown_0.set_selected_highlight(True)
get_option_count()

Clear all options in a drop-down list.

Returns:

The number of options in the dropdown.

Return type:

int

UiFlow2 Code Block:

get_option_count.png

MicroPython Code Block:

option_count = dropdown_0.get_option_count()
get_option_index(option)

Get the index of an option.

Parameters:

option (str) – The option to find.

Returns:

The index of the option, or -1 if not found.

Return type:

int

UiFlow2 Code Block:

get_option_index.png

MicroPython Code Block:

index = dropdown_0.get_option_index("Option 1")
if index != -1:
    print(f"Option found at index: {index}")
else:
    print("Option not found")
get_text()

Get text of the drop-down list’s button.

Returns:

The text of the dropdown button.

Return type:

str

UiFlow2 Code Block:

get_text.png

MicroPython Code Block:

text = dropdown_0.get_text()
print(f"Dropdown button text: {text}")
set_text(txt)

Set text of the drop-down list’s button.

Parameters:

txt (str) – The text to set for the dropdown button.

Returns:

None

UiFlow2 Code Block:

set_text.png

MicroPython Code Block:

dropdown_0.set_text("Select an option")
add_event_cb(handler, event, user_data)

Add an event callback to the dropdown. The callback will be called when the specified event occurs.

Parameters:

  • handler (function) – The callback function to call.

  • event (int) – The event to listen for.

  • user_data (Any) – Optional user data to pass to the callback.

Returns:

None

UiFlow2 Code Block:

event.png

MicroPython Code Block:

def dropdown_0_value_changed_event(event_struct):
    global dropdown_0
    selected = dropdown_0.get_selected_str()
    print(f"Selected: {selected}")

def dropdown_0_event_handler(event_struct):
    global dropdown_0
    event = event_struct.code
    if event == lv.EVENT.VALUE_CHANGED:
        dropdown_0_value_changed_event(event_struct)
    return

dropdown_0.add_event_cb(dropdown_0_event_handler, lv.EVENT.ALL, None)
set_options(options)

Set the options for the dropdown.

Parameters:

options (list) – A list of options to display in the dropdown.

UiFlow2 Code Block:

set_options.png

MicroPython Code Block:

dropdown_0.set_options(["option1", "option2", "option3"])
get_options()

Get the list of options in the dropdown.

Returns:

The list of options.

Return type:

list

add_option(option, pos)

Add an option to the dropdown at a specific position.

Parameters:

  • option (str) – The option to add.

  • pos (int) – The position to insert the option at.

Return type:

None

UiFlow2 Code Block:

add_option.png

MicroPython Code Block:

dropdown_0.add_option("New Option", 1)
clear_options()

Clear all options in the dropdown.

UiFlow2 Code Block:

clear_options.png

MicroPython Code Block:

dropdown_0.clear_options()
Return type:

None

get_selected_str()

Get the currently selected option as a string.

Returns:

The selected option as a string.

Return type:

str

UiFlow2 Code Block:

get_selected_str.png

MicroPython Code Block:

selected_option = dropdown_0.get_selected_str()
set_dir(direction)

Set the direction of the dropdown.

Parameters:

direction (int) – The direction of the dropdown, can be lv.DIR.LEFT, lv.DIR.RIGHT, lv.DIR.TOP, or lv.DIR.BOTTOM.

Return type:

None

UiFlow2 Code Block:

set_dir.png

MicroPython Code Block:

dropdown_0.set_dir(lv.DIR.LEFT)
set_style_radius(radius, part)

Set the radius of the dropdown’s corners.

Parameters:

  • radius (int) – The radius of the corners in pixels.

  • part (int) – The part of the dropdown to apply the radius to, e.g., lv.PART.MAIN.

Return type:

None

UiFlow2 Code Block:

None

MicroPython Code Block:

dropdown_0.set_style_radius(10, lv.PART.MAIN | lv.STATE.DEFAULT)
set_size(w, h)

Set the size of the dropdown.

Parameters:

  • w (int) – The width of the dropdown.

  • h (int) – The height of the dropdown.

Return type:

None

UiFlow2 Code Block:

set_size.png

MicroPython Code Block:

dropdown_0.set_size(150, 40)