Quick search

Table Of Contents

Source code for kivy.uix.dropdown

Drop-Down List

.. image:: images/dropdown.gif
    :align: right

.. versionadded:: 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 :meth:`` 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:

        # 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,

    # 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
            text: 'Unselectable item'
            size_hint_y: None
            height: 44
            text: 'My second Item'
            size_hint_y: None
            height: 44

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))

__all__ = ('DropDown', )

from kivy.uix.scrollview import ScrollView
from import ObjectProperty, NumericProperty, BooleanProperty
from kivy.core.window import Window
from kivy.lang import Builder
from kivy.clock import Clock
from kivy.config import Config

_grid_kv = '''
    size_hint_y: None
    height: self.minimum_size[1]
    cols: 1

class DropDownException(Exception):
    '''DropDownException class.

if __name__ == '__main__':
    from kivy.uix.button import Button
    from kivy.base import runTouchApp

    def show_dropdown(button, *largs):
        dp = DropDown()
        dp.bind(on_select=lambda instance, x: setattr(button, 'text', x))
        for i in range(10):
            item = Button(text='hello %d' % i, size_hint_y=None, height=44)
            item.bind(on_release=lambda btn:

    def touch_move(instance, touch): = touch.pos

    btn = Button(text='SHOW', size_hint=(None, None), pos=(300, 200))
    btn.bind(on_release=show_dropdown, on_touch_move=touch_move)