Quick search

Drop-Down List


New in version 1.4.0.

A versatile drop-down list that can be used with custom widgets. It allows you to display a list of widgets under a displayed widget. Unlike other toolkits, the list of widgets can contain any type of widget: simple buttons, images etc.

The positioning of the drop-down list is fully automatic: we will always try to place the dropdown list in a way that the user can select an item in the list.

Basic example

A button with a dropdown list of 10 possible values. All the buttons within the dropdown list will trigger the dropdown DropDown.select() method. After being called, the main button text will display the selection of the dropdown.

from kivy.uix.dropdown import DropDown
from kivy.uix.button import Button
from kivy.base import runTouchApp

# create a dropdown with 10 buttons
dropdown = DropDown()
for index in range(10):
    # When adding widgets, we need to specify the height manually
    # (disabling the size_hint_y) so the dropdown can calculate
    # the area it needs.

    btn = Button(text='Value %d' % index, size_hint_y=None, height=44)

    # for each button, attach a callback that will call the select() method
    # on the dropdown. We'll pass the text of the button as the data of the
    # selection.
    btn.bind(on_release=lambda btn: dropdown.select(btn.text))

    # then add the button inside the dropdown

# create a big main button
mainbutton = Button(text='Hello', size_hint=(None, None))

# show the dropdown menu when the main button is released
# note: all the bind() calls pass the instance of the caller (here, the
# mainbutton instance) as the first argument of the callback (here,
# dropdown.open.).

# one last thing, listen for the selection in the dropdown list and
# assign the data to the button text.
dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x))


Extending dropdown in Kv

You could create a dropdown directly from your kv:

#:kivy 1.4.0
        text: 'My first Item'
        size_hint_y: None
        height: 44
        on_release: root.select('item1')
        text: 'Unselectable item'
        size_hint_y: None
        height: 44
        text: 'My second Item'
        size_hint_y: None
        height: 44
        on_release: root.select('item2')

And then, create the associated python class and use it:

class CustomDropDown(DropDown):

dropdown = CustomDropDown()
mainbutton = Button(text='Hello', size_hint=(None, None))
dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x))
class kivy.uix.dropdown.DropDown(**kwargs)[source]

Bases: kivy.uix.scrollview.ScrollView

DropDown class. See module documentation for more information.

on_select: data

Fired when a selection is done. The data of the selection is passed in as the first argument and is what you pass in the select() method as the first argument.


New in version 1.8.0.

Fired when the DropDown is dismissed, either on selection or on touching outside the widget.


(internal) Property that will be set to the widget to which the drop down list is attached.

The open() method will automatically set this property whilst dismiss() will set it back to None.


By default, the dropdown will be automatically dismissed when a touch happens outside of it, this option allows to disable this feature

auto_dismiss is a BooleanProperty and defaults to True.

New in version 1.8.0.


By default, the width of the dropdown will be the same as the width of the attached widget. Set to False if you want to provide your own width.

auto_width is a BooleanProperty and defaults to True.


(internal) Property that will be set to the container of the dropdown list. It is a GridLayout by default.


Remove the dropdown widget from the window and detach it from the attached widget.


By default, the dropdown will be automatically dismissed when a selection has been done. Set to False to prevent the dismiss.

dismiss_on_select is a BooleanProperty and defaults to True.


Indicate the maximum height that the dropdown can take. If None, it will take the maximum height available until the top or bottom of the screen is reached.

max_height is a NumericProperty and defaults to None.


Minimum time before the DropDown is dismissed. This is used to allow for the widget inside the dropdown to display a down state or for the DropDown itself to display a animation for closing.

min_state_time is a NumericProperty and defaults to the Config value min_state_time.

New in version 1.10.0.


Open the dropdown list and attach it to a specific widget. Depending on the position of the widget within the window and the height of the dropdown, the dropdown might be above or below that widget.


Call this method to trigger the on_select event with the data selection. The data can be anything you want.