Dropdown¶
Dropdowns present a list of options that appear below a trigger element. Filter field variants combine a text field with a dropdown for searchable selection.
Variants¶
| Class | Description |
|---|---|
MorphDropdownList |
Scrollable option list |
MorphDropdownMenu |
Full dropdown menu with animation |
MorphDropdownFilterField |
Text field + dropdown for filtered selection |
MorphDropdownFilterFieldOutlined |
Outlined variant |
MorphDropdownFilterFieldRounded |
Rounded variant |
MorphDropdownFilterFieldFilled |
Filled variant |
Usage¶
from morphui.uix.dropdown import MorphDropdownFilterField
field = MorphDropdownFilterField(
hint_text="Select category",
options=['Electronics', 'Clothing', 'Books', 'Food'],
on_select=self.on_category_selected,
)
morphui.uix.dropdown
¶
Dropdown menu and filter field widgets for MorphUI.
Dropdowns present a selectable list of options anchored below a trigger widget. Filter field variants combine a text input with the dropdown for in-place searchable selection.
| CLASS | DESCRIPTION |
|---|---|
MorphDropdownList |
Scrollable list of selectable options. |
MorphDropdownMenu |
Animated dropdown menu that opens below a trigger widget. |
MorphDropdownFilterField |
Text field with attached dropdown for filtered selection (filled). |
MorphDropdownFilterFieldOutlined |
Outlined variant of the filter field. |
MorphDropdownFilterFieldRounded |
Rounded variant of the filter field. |
MorphDropdownFilterFieldFilled |
Explicit filled variant of the filter field. |
MorphDropdownList(**kwargs)
¶
Bases: BaseListView
A dropdown list widget that combines list view with menu motion.
This widget extends :class:~morphui.uix.list.BaseListView with
dropdown menu capabilities, including open/dismiss animations and
elevation effects. It's designed to work seamlessly with
:class:~morphui.uix.dropdown.MorphDropdownFilterField.
set_focus_by_text(text)
¶
Set focus to the child item with the specified label text.
| PARAMETER | DESCRIPTION |
|---|---|
text
|
The label text of the item to focus.
TYPE:
|
set_neighbor_focus(current_focus_child, direction)
¶
Set focus to the neighboring child item in the specified direction.
| PARAMETER | DESCRIPTION |
|---|---|
current_focus_child
|
The currently focused child item.
TYPE:
|
direction
|
The direction to move focus, either 'up' or 'down'.
TYPE:
|
scroll_by_item(direction, n_items)
¶
Scroll the list by the specified number of items in the given direction.
| PARAMETER | DESCRIPTION |
|---|---|
direction
|
The direction to scroll, either 'up' or 'down'.
TYPE:
|
n_items
|
The number of items to scroll by.
TYPE:
|
on_arrow_down_press()
¶
Handle the arrow down key press event.
This method is called when the arrow down key is pressed. It moves the focus to the next item in the list.
on_arrow_up_press()
¶
Handle the arrow up key press event.
This method is called when the arrow up key is pressed. It moves the focus to the previous item in the list.
on_enter_press()
¶
Handle the enter key press event.
This method is called when the enter key is pressed. It triggers the release action on the currently focused item.
MorphDropdownMenu(**kwargs)
¶
Bases: MorphMenuMotionBehavior, MorphSizeBoundsBehavior, MorphElevationBoxLayout
A base dropdown menu class with color theme, surface layer, elevation, and menu motion behaviors.
items = AliasProperty(lambda self: self.dropdown_list._get_items(), lambda self, items: self.dropdown_list._set_items(items))
class-attribute
instance-attribute
¶
The list of items in the dropdown menu.
This property provides access to the items displayed in the dropdown list. It allows getting and setting the list of items.
:attr:items is a :class:~kivy.properties.AliasProperty.
item_release_callback = AliasProperty(lambda self: self.dropdown_list.item_release_callback, lambda self, callback: setattr(self.dropdown_list, 'item_release_callback', callback))
class-attribute
instance-attribute
¶
Callback function for item release events.
This property allows getting and setting the callback function that is called when an item in the dropdown list is released.
:attr:items_release_callback is a
:class:~kivy.properties.AliasProperty.
default_config = dict(theme_color_bindings=(dict(normal_surface_color='surface_container_highest_color')), size_lower_bound=(150, 100), size_hint=(None, None), radius=[0, 0, dp(8), dp(8)], padding=(dp(8)), elevation=2, same_width_as_caller=True)
class-attribute
instance-attribute
¶
Default configuration for the MorphDropdownMenu.
dropdown_list = MorphDropdownList()
class-attribute
instance-attribute
¶
The dropdown list associated with this menu.
This property holds a reference to the :class:MorphDropdownList
instance that is linked to this filter field.
:attr:dropdown is a :class:~kivy.properties.ObjectProperty and
defaults to None.
layout_manager = self.dropdown_list.layout_manager
class-attribute
instance-attribute
¶
The layout manager for the dropdown list.
This property holds a reference to the layout manager used by the dropdown list to arrange its items. It is set during initialization.
:attr:layout_manager is a :class:~kivy.properties.ObjectProperty
and defaults to None.
on_pre_open(*args)
¶
Handle actions before the dropdown menu opens.
This method is called just before the dropdown menu is opened. It sets the focus in the dropdown list based on the caller's current text value.
on_dismiss(*args)
¶
Handle actions after the dropdown menu is dismissed.
This method is called just after the dropdown menu is dismissed. It clears the focus and hover states from all items in the dropdown list.
on_is_open(instance, value)
¶
Handle changes to the is_open property.
This method is called whenever the is_open property changes.
It updates the key_press_enabled property of the dropdown list
to match the new state of is_open.
| PARAMETER | DESCRIPTION |
|---|---|
instance
|
The instance of the dropdown menu where the change occurred.
TYPE:
|
value
|
The new value of the
TYPE:
|
MorphDropdownSelect(kw_dropdown={}, **kwargs)
¶
Bases: MorphToggleButtonBehavior, MorphTextIconButton
This is a simple dropdown select button that can be used to trigger a dropdown menu.
This button displays an icon that changes depending on whether
the dropdown menu is open or closed. It is designed to work with
:class:~morphui.uix.dropdown.MorphDropdownMenu.
Examples:
Basic usage with a simple list of items:
from morphui.app import MorphApp
from morphui.uix.floatlayout import MorphFloatLayout
from morphui.uix.dropdown import MorphDropdownSelect
class MyApp(MorphApp):
def build(self) -> MorphFloatLayout:
self.theme_manager.theme_mode = 'Dark'
self.theme_manager.seed_color = 'morphui_teal'
layout = MorphFloatLayout(
MorphDropdownSelect(
identity='dropdown_button',
items=[
{'label_text': f'Item {i}'} for i in range(10)],
pos_hint={'center_x': 0.5, 'center_y': 0.9},))
self.dropdown_button = layout.identities.dropdown_button
return layout
if __name__ == '__main__':
MyApp().run()
normal_icon = StringProperty('chevron-down')
class-attribute
instance-attribute
¶
Icon for the normal (closed) state of the dropdown filter field.
This property holds the icon name used when the dropdown is in its normal (closed) state.
:attr:normal_icon is a
:class:~kivy.properties.StringProperty and defaults to
'chevron-down'.
active_icon = StringProperty('chevron-up')
class-attribute
instance-attribute
¶
Icon for the focused (open) state of the dropdown filter field.
This property holds the icon name used when the dropdown is in its focused (open) state.
:attr:active_icon is a
:class:~kivy.properties.StringProperty and defaults to
'chevron-up'.
dropdown_menu = MorphDropdownMenu(**kw_dropdown)
class-attribute
instance-attribute
¶
The dropdown menu associated with this filter field.
This property holds a reference to the :class:MorphDropdownMenu
instance that is linked to this filter field.
:attr:dropdown_menu is a :class:~kivy.properties.ObjectProperty and
defaults to None.
on_release()
¶
Toggle the dropdown menu when the button is released.
on_item_release(item, index)
¶
Event handler for item release events.
This method is called when an item in the dropdown list is released. It can be overridden to provide custom behavior when an item is selected.
| PARAMETER | DESCRIPTION |
|---|---|
item
|
The item that was released.
TYPE:
|
index
|
The index of the released item in the dropdown list.
TYPE:
|
Notes
This method is not called if an item_release_callback is
provided during initialization.
MorphDropdownFilterField(kw_dropdown={}, **kwargs)
¶
Bases: MorphTextField
A text field used for filtering items in a dropdown list.
Inherits from :class:~morphui.uix.textfield.MorphTextField and
is designed to be used within dropdown lists to provide
filtering capabilities.
Examples:
Basic usage with a simple list of items:
from morphui.app import MorphApp
from morphui.uix.floatlayout import MorphFloatLayout
from morphui.uix.dropdown import MorphDropdownFilterField
class MyApp(MorphApp):
def build(self) -> MorphFloatLayout:
self.theme_manager.theme_mode = 'Dark'
self.theme_manager.seed_color = 'morphui_teal'
icon_items = [
{
'label_text': icon_name,
'leading_icon': icon_name,}
for icon_name in sorted(self.typography.icon_map.keys())]
layout = MorphFloatLayout(
MorphDropdownFilterField(
identity='icon_picker',
items=icon_items,
item_release_callback=self.icon_selected_callback,
heading_text='Search icons...',
leading_icon='magnify',
pos_hint={'center_x': 0.5, 'center_y': 0.9},
size_hint=(0.8, None),))
self.icon_picker = layout.identities.icon_picker
return layout
def icon_selected_callback(self, item, index):
self.icon_picker.text = item.label_text
self.icon_picker.leading_icon = item.label_text
if __name__ == '__main__':
MyApp().run()
Advanced example - Icon picker with all available icons:
from morphui.app import MorphApp
from morphui.uix.floatlayout import MorphFloatLayout
from morphui.uix.dropdown import MorphDropdownFilterField
class MyApp(MorphApp):
def build(self) -> MorphFloatLayout:
self.theme_manager.theme_mode = 'Dark'
self.theme_manager.seed_color = 'morphui_teal'
icon_items = [
{
'label_text': icon_name,
'leading_icon': icon_name,}
for icon_name in sorted(self.typography.icon_map.keys())]
layout = MorphFloatLayout(
MorphDropdownFilterField(
identity='icon_picker',
items=icon_items,
item_release_callback=self.icon_selected_callback,
heading_text='Search icons...',
trailing_icon='magnify',
pos_hint={'center_x': 0.5, 'center_y': 0.9},
size_hint=(0.8, None),))
self.icon_picker = layout.identities.icon_picker
return layout
def icon_selected_callback(self, item, index):
self.icon_picker.text = item.label_text
self.icon_picker.leading_icon = item.label_text
self.icon_picker.dropdown.dismiss()
if __name__ == '__main__':
MyApp().run()
normal_trailing_icon = StringProperty('chevron-down')
class-attribute
instance-attribute
¶
Icon for the normal (closed) state of the dropdown filter field.
This property holds the icon name used when the dropdown is in its normal (closed) state.
:attr:normal_trailing_icon is a
:class:~kivy.properties.StringProperty and defaults to
'chevron-down'.
focus_trailing_icon = StringProperty('chevron-up')
class-attribute
instance-attribute
¶
Icon for the focused (open) state of the dropdown filter field.
This property holds the icon name used when the dropdown is in its focused (open) state.
:attr:focus_trailing_icon is a
:class:~kivy.properties.StringProperty and defaults to
'chevron-up'.
default_config = MorphTextField.default_config.copy() | dict()
class-attribute
instance-attribute
¶
Default configuration for the MorphDropdownFilterField.
dropdown_menu = MorphDropdownMenu(**kw_dropdown)
class-attribute
instance-attribute
¶
The dropdown menu associated with this filter field.
This property holds a reference to the :class:MorphDropdownMenu
instance that is linked to this filter field.
:attr:dropdown_menu is a :class:~kivy.properties.ObjectProperty and
defaults to None.
on_item_release(item, index)
¶
Event handler for item release events.
This method is called when an item in the dropdown list is released. It can be overridden to provide custom behavior when an item is selected.
| PARAMETER | DESCRIPTION |
|---|---|
item
|
The item that was released.
TYPE:
|
index
|
The index of the released item in the dropdown list.
TYPE:
|
Notes
This method is not called if an item_release_callback is
provided during initialization.
MorphDropdownFilterFieldOutlined(kw_dropdown={}, **kwargs)
¶
Bases: MorphDropdownFilterField
An outlined text field used for filtering items in a dropdown menu.
Uses same default configuration as
:class:~morphui.uix.textfield.MorphTextFieldOutlined
default_config = MorphTextFieldOutlined.default_config.copy() | dict()
class-attribute
instance-attribute
¶
Default configuration for the
:class:MorphDropdownFilterFieldOutlined.
MorphDropdownFilterFieldRounded(**kwargs)
¶
Bases: MorphRoundSidesBehavior, MorphDropdownFilterField
A rounded text field used for filtering items in a dropdown menu.
Uses same default configuration as
:class:~morphui.uix.textfield.MorphTextFieldRounded
default_config = MorphTextFieldRounded.default_config.copy() | dict()
class-attribute
instance-attribute
¶
Default configuration for the
:class:MorphDropdownFilterFieldRounded.
MorphDropdownFilterFieldFilled(kw_dropdown={}, **kwargs)
¶
Bases: MorphDropdownFilterField
A filled text field used for filtering items in a dropdown menu.
Uses same default configuration as
:class:~morphui.uix.textfield.MorphTextFieldFilled
default_config = MorphTextFieldFilled.default_config.copy() | dict()
class-attribute
instance-attribute
¶
Default configuration for the
:class:MorphDropdownFilterFieldFilled.
MorphDropdownMultiselect(**kwargs)
¶
Bases: MorphDropdownFilterField
Morph Dropdown Multiselect component.
A multiselect dropdown allows users to select multiple items from a dropdown list. Selected items are displayed as chips within the dropdown field.
This component combines various behaviors to provide a rich user experience, including theming, typography, and interaction layers. It is designed to be used in conjunction with a dropdown menu that provides the list of selectable items.
Examples:
Basic usage with a simple list of items:
from morphui.app import MorphApp
from morphui.uix.floatlayout import MorphFloatLayout
from morphui.uix.dropdown import MorphDropdownMultiselect
class MyApp(MorphApp):
def build(self) -> MorphFloatLayout:
self.theme_manager.theme_mode = 'Dark'
self.theme_manager.seed_color = 'morphui_teal'
return MorphFloatLayout(
MorphDropdownMultiselect(
identity='my_widget',
heading_text='Select Items',
items=[
{'label_text': i}
for i in ['Item 1', 'Item 2', 'Item 3']],
required=True,
pos_hint={'center_x': 0.5, 'center_y': 0.5},),
theme_color_bindings=dict(
normal_surface_color='background_color'),)
if __name__ == '__main__':
MyApp().run()
Different kinds of the dropdown multiselect: ```python from morphui.app import MorphApp from morphui.uix.floatlayout import MorphFloatLayout from morphui.uix.dropdown import MorphDropdownMultiselectOutlined from morphui.uix.dropdown import MorphDropdownMultiselectRounded from morphui.uix.dropdown import MorphDropdownMultiselectFilled
class MyApp(MorphApp): def build(self) -> MorphFloatLayout: self.theme_manager.theme_mode = 'Dark' self.theme_manager.seed_color = 'morphui_teal' items = [ {'label_text': f'Item {i}'} for i in range(1, 6)]
return MorphFloatLayout(
MorphDropdownMultiselectOutlined(
heading_text='Outlined Multiselect',
leading_icon='database-check',
identity='outlined',
items=items,
pos_hint={'center_x': 0.5, 'center_y': 0.9},
size_hint=(0.8, None),),
MorphDropdownMultiselectRounded(
heading_text='Rounded Multiselect',
leading_icon='email-check',
identity='rounded',
items=items,
pos_hint={'center_x': 0.5, 'center_y': 0.7},
size_hint=(0.8, None),),
MorphDropdownMultiselectFilled(
heading_text='Filled Multiselect',
leading_icon='filter-check',
identity='filled',
items=items,
pos_hint={'center_x': 0.5, 'center_y': 0.5},
size_hint=(0.8, None),),
theme_color_bindings=dict(
normal_surface_color='background_color'),)
if name == 'main': MyApp().run()
normal_trailing_icon = StringProperty('check-all')
class-attribute
instance-attribute
¶
Icon for the normal state of the dropdown filter field.
This property holds the icon name used when the dropdown is in it's normal state, typically indicating that no options are selected.
:attr:normal_trailing_icon is a
:class:~kivy.properties.StringProperty and defaults to
'check-all'.
active_trailing_icon = StringProperty('close')
class-attribute
instance-attribute
¶
Icon for the active state of the dropdown filter field.
This property holds the icon name used when the dropdown is in its active state, typically indicating that some options are selected.
:attr:active_trailing_icon is a
:class:~kivy.properties.StringProperty and defaults to
'close-circle-multiple-outline'.
active = AliasProperty(lambda self: bool(self.selected_options) and not bool(self.text), None, bind=['selected_options', 'text'])
class-attribute
instance-attribute
¶
Whether the dropdown filter field is active (read-only).
This property indicates whether the dropdown filter field is active, which is determined by whether there are any selected options. It is read-only and cannot be set directly.
:attr:active is a :class:~kivy.properties.AliasProperty and
is bound to the selected_options property, updating automatically
whenever the selected options change.
selected_options = AliasProperty(_get_selected_options, None, bind=['_chips'])
class-attribute
instance-attribute
¶
List of currently selected options in the multiselect dropdown.
This property holds the list of options that are currently selected in the multiselect dropdown. It can be used to get or set the selected options programmatically.
:attr:selected_options is a :class:~kivy.properties.AliasProperty
and defaults to an empty list.
input_widget
property
¶
The internal text input widget (read-only).
This property provides access to the internal
:class:MorphStackLayout widget that is used for handling user
input. It allows external code to interact with the stack layout
widget directly if needed. Internal it is used to bind
properties for bidirectional updates and to set properties like
padding and maximum height.
| RETURNS | DESCRIPTION |
|---|---|
MorphStackLayout
|
The internal stack layout widget. |
on_options_container_children(instance, children)
¶
Handle changes to the children of the options container.
This method is called whenever the children of the options
container change, such as when a new chip is added or an
existing chip is removed. It checks if the internal text input
is still a child of the options container before dispatching the
:method:on_selection_change event, ensuring that the event is
only triggered when the text input is present.
Notes
The event is dispatched using Clock.schedule_once to ensure
that it is executed in the next frame, allowing the UI to update
before the event is handled. This is important to allow the
addition or removal of chips to be reflected in the UI before
any further processing occurs.
on_selection_change(*args)
¶
Event handler for selection change events.
This method is called whenever the selection of options changes, such as when a new option is added or an existing option is removed. It can be overridden to provide custom behavior when the selection changes.
on_enter_press(*args)
¶
Handle the event when the user presses Enter in the text input.
This method is called when the user presses the Enter key while the text input is focused. It can be overridden to provide custom behavior when the user submits their input.
on_item_release(item, index)
¶
Event handler for item release events.
This method is called when an item in the dropdown list is released. It can be overridden to provide custom behavior when an item is selected.
| PARAMETER | DESCRIPTION |
|---|---|
item
|
The item that was released.
TYPE:
|
index
|
The index of the released item in the dropdown list.
TYPE:
|
add_selected_option(option)
¶
Add an option to the list of selected options.
This method adds a new option to the list of selected options in the multiselect dropdown. It creates a new chip for the option and adds it to the internal stack layout.
| PARAMETER | DESCRIPTION |
|---|---|
option
|
The option to be added to the list of selected options.
TYPE:
|
validate(text)
¶
Validate the current text input.
This method checks the current text input against the defined validation rules and updates the error state accordingly.
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the input is valid, False otherwise. |
MorphDropdownMultiselectOutlined(**kwargs)
¶
Bases: MorphDropdownMultiselect
An outlined version of the MorphDropdownMultiselect component.
Uses same default configuration as
:class:~morphui.uix.textfield.MorphTextFieldOutlined
Examples:
Basic usage with a simple list of items:
```python from morphui.app import MorphApp from morphui.uix.floatlayout import MorphFloatLayout from morphui.uix.dropdown import MorphDropdownMultiselectOutlined
class MyApp(MorphApp): def build(self) -> MorphFloatLayout: self.theme_manager.theme_mode = 'Dark' self.theme_manager.seed_color = 'morphui_teal' return MorphFloatLayout( MorphDropdownMultiselectOutlined( identity='my_widget', heading_text='Select Items', items=[ {'label_text': i} for i in ['Item 1', 'Item 2', 'Item 3']], required=True, pos_hint={'center_x': 0.5, 'center_y': 0.5},), theme_color_bindings=dict( normal_surface_color='background_color'),)
if name == 'main': MyApp().run()
default_config = MorphDropdownMultiselect.default_config.copy() | MorphTextFieldOutlined.default_config.copy()
class-attribute
instance-attribute
¶
Default configuration for the
:class:MorphDropdownMultiselectOutlined.
MorphDropdownMultiselectRounded(**kwargs)
¶
Bases: MorphRoundSidesBehavior, MorphDropdownMultiselect
A rounded version of the MorphDropdownMultiselect component.
Uses same default configuration as
:class:~morphui.uix.textfield.MorphTextFieldRounded
Examples:
Basic usage with a simple list of items:
```python from morphui.app import MorphApp from morphui.uix.floatlayout import MorphFloatLayout from morphui.uix.dropdown import MorphDropdownMultiselectRounded
class MyApp(MorphApp): def build(self) -> MorphFloatLayout: self.theme_manager.theme_mode = 'Dark' self.theme_manager.seed_color = 'morphui_teal' return MorphFloatLayout( MorphDropdownMultiselectRounded( identity='my_widget', heading_text='Select Items', items=[ {'label_text': i} for i in ['Item 1', 'Item 2', 'Item 3']], required=True, pos_hint={'center_x': 0.5, 'center_y': 0.5},), theme_color_bindings=dict( normal_surface_color='background_color'),)
if name == 'main': MyApp().run()
default_config = MorphDropdownMultiselect.default_config.copy() | MorphTextFieldRounded.default_config.copy()
class-attribute
instance-attribute
¶
Default configuration for the
:class:MorphDropdownMultiselectRounded.
MorphDropdownMultiselectFilled(**kwargs)
¶
Bases: MorphDropdownMultiselect
A filled version of the MorphDropdownMultiselect component.
Uses same default configuration as
:class:~morphui.uix.textfield.MorphTextFieldFilled
Examples:
Basic usage with a simple list of items:
```python from morphui.app import MorphApp from morphui.uix.floatlayout import MorphFloatLayout from morphui.uix.dropdown import MorphDropdownMultiselectFilled
class MyApp(MorphApp): def build(self) -> MorphFloatLayout: self.theme_manager.theme_mode = 'Dark' self.theme_manager.seed_color = 'morphui_teal' return MorphFloatLayout( MorphDropdownMultiselectFilled( identity='my_widget', heading_text='Select Items', items=[ {'label_text': i} for i in ['Item 1', 'Item 2', 'Item 3']], required=True, pos_hint={'center_x': 0.5, 'center_y': 0.5},), theme_color_bindings=dict( normal_surface_color='background_color'),)
if name == 'main': MyApp().run()
default_config = MorphDropdownMultiselect.default_config.copy() | MorphTextFieldFilled.default_config.copy()
class-attribute
instance-attribute
¶
Default configuration for the
:class:MorphDropdownMultiselectFilled.