Search

See also

Material Design spec, Search

Search allows users to enter a keyword or phrase to get relevant information.

Usage

MDSearchBar:
    id: search_bar
    supporting_text: "Search in text"
    view_root: root

    # Search Bar.
    MDSearchBarLeadingContainer:
        MDSearchLeadingIcon:
            icon: "menu"
            on_release: app.open_menu(self)

    MDSearchBarTrailingContainer:

        MDSearchTrailingIcon:
            icon:"microphone"

        MDSearchTrailingAvatar:
            source:f"{images_path}/logo/kivymd-icon-128.png"

    # Search View.
    MDSearchViewLeadingContainer:

        MDSearchLeadingIcon:
            icon: "arrow-left"
            on_release: search_bar.close_view()

    MDSearchViewTrailingContainer:

        MDSearchTrailingIcon:
            icon: "window-close"

    MDSearchViewContainer:
        ...

Anatomy

Full example

Imperative KV styleDeclarative python style

from kivy.lang import Builder
from kivy.properties import StringProperty

from kivymd.app import MDApp
from kivymd.icon_definitions import md_icons
from kivymd.uix.list import MDListItem


class IconItem(MDListItem):
    icon = StringProperty()
    text = StringProperty()


KV = '''
#:import images_path kivymd.images_path

<IconItem>
    theme_bg_color: "Custom"
    md_bg_color: [0, 0, 0, 0]

    MDListItemLeadingIcon:
        icon: root.icon

    MDListItemSupportingText:
        text: root.text


MDScreen:
    md_bg_color: app.theme_cls.backgroundColor

    BoxLayout:
        padding: [dp(10), dp(30), dp(10), dp(10)]
        orientation: "vertical"

        MDSearchBar:
            id: search_bar
            supporting_text: "Search in text"
            view_root: root
            on_text: app.set_list_md_icons(text=args[-1], search=True)

            # Search Bar items.
            MDSearchBarLeadingContainer:

                MDSearchLeadingIcon:
                    icon: "menu"
                    on_release: print("Menu pressed")

            MDSearchBarTrailingContainer:

                MDSearchTrailingIcon:
                    icon: "microphone"
                    on_press: print("Microphone pressed")

                MDSearchTrailingAvatar:
                    source: f"{images_path}/logo/kivymd-icon-128.png"
                    on_press: print("Avatar pressed")

            # Search View.
            MDSearchViewLeadingContainer:

                MDSearchLeadingIcon:
                    icon: "arrow-left"
                    on_release: search_bar.close_view()

            MDSearchViewTrailingContainer:

                MDSearchTrailingIcon:
                    icon: "window-close"
                    on_release: search_bar.text = ""

            MDSearchViewContainer:

                RecycleView:
                    id: rv
                    key_viewclass: 'viewclass'
                    key_size: 'height'

                    RecycleBoxLayout:
                        default_size: None, dp(48)
                        default_size_hint: 1, None
                        size_hint_y: None
                        height: self.minimum_height
                        orientation: 'vertical'

        Widget:

        BoxLayout:
            size_hint_y: None
            height: dp(30)
            spacing: dp(10)

            MDLabel:
                text: "Bar dock"
                halign: "right"

            MDSwitch:
                on_active: search_bar.docked = args[-1]
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)

    def on_select_text(self, text):
        self.root.ids.search_bar.text = text

    def on_start(self):
        self.set_list_md_icons()

    def set_list_md_icons(self, text="", search=False):
        def add_icon_item(name_icon):
            self.root.ids.rv.data.append(
                {
                    "viewclass": "IconItem",
                    "icon": name_icon,
                    "text": name_icon,
                    "on_release": lambda y=name_icon: self.on_select_text(y),
                }
            )

        self.root.ids.rv.data = []

        for name_icon in md_icons.keys():
            if search:
                if text in name_icon:
                    add_icon_item(name_icon)
            else:
                add_icon_item(name_icon)


Example().run()

API - kivymd.uix.search.search

class kivymd.uix.search.search.MDSearchTrailingAvatar(**kwargs)

Trailing avatar class.

For more information, see in the ButtonBehavior and Image classes documentation.

class kivymd.uix.search.search.MDSearchLeadingIcon(**kwargs)

Leading icon class.

For more information, see in the ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.search.search.MDSearchTrailingIcon(**kwargs)

Trailing icon class.

For more information, see in the ButtonBehavior and MDIcon classes documentation.

class kivymd.uix.search.search.MDSearchBarTrailingContainer(*args, **kwargs)

Trailing container class for search bar.

For more information, see in the BoxLayout class documentation.

class kivymd.uix.search.search.MDSearchBarLeadingContainer(*args, **kwargs)

Leading container class for search bar.

For more information, see in the BoxLayout class documentation.

class kivymd.uix.search.search.MDSearchViewTrailingContainer(*args, **kwargs)

Trailing container class for search view.

For more information, see in the BoxLayout class documentation.

class kivymd.uix.search.search.MDSearchViewLeadingContainer(*args, **kwargs)

Leading container class for search view.

For more information, see in the BoxLayout class documentation.

class kivymd.uix.search.search.MDSearchViewContainer(*args, **kwargs)

A container for widgets that are displayed when the search bar is in focus.

For more information, see in the BoxLayout class documentation.

add_widget(widget, *args, **kwargs)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

Added in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

show_child(anim_time: float) → None

Displays the stored child widget with a fade-in animation.

Parameters:

anim_time – Delay before showing the widget.

hide_child() → None

Removes the stored child widget from the layout.

remove_widget(widget)

Remove a widget from the children of this widget.

Parameters:

widget: Widget

Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

class kivymd.uix.search.search.MDSearchBar(*args, **kwargs)

Search bar class.

For more information, see in the Widget class documentation.

leading_icon

Leading icon name.

leading_icon is an StringProperty and defaults to ‘magnify’.

supporting_text

Supporting text.

supporting_text is an StringProperty and defaults to ‘Hinted search text’.

view_root

Root widget for search view.

view_root is an ObjectProperty and defaults to None.

docked_width

Docked width.

docked_width is an NumericProperty and defaults to dp(360).

docked_height

Docked height.

docked_height is an NumericProperty and defaults to dp(240).

docked

If True, the search bar will be docked.

docked is an BooleanProperty and defaults to False.

text

Search query text.

text is an StringProperty and defaults to ‘’.

on_docked(instance, docked) → None

Called when the docked property changes.

Parameters:

• instance – The MDSearchBar instance.

• docked – The new docked value (True/False).

Updates the size_hint_x and width accordingly. When docked, sets a fixed width using docked_width property.

on_supporting_text(instance, text: str) → None

Called when the supporting_text property changes.

Parameters:

• instance – The MDSearchBar instance.

• text – The new supporting text.

Updates the hint text of the text input field to display the provided supporting text.

on_view_root(*args) → None

Called when the view_root property changes.

Parameters:

args – Arguments passed to the method.

Removes the search widget from its current parent (if any), adds it to the new view_root, and initializes the search widget state and position.

add_widget(widget)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

Added in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

close_view() → None

Closes the search view.

open_view() → None

Opens the search view.

on_open() → None

Event handler for the on_open event.

Override this method in subclasses to handle the search view opening event.

on_close() → None

Event handler for the on_close event.

Override this method in subclasses to handle the search view closing event.

on_text(*args) → None

Called when the text property changes.

Parameters:

args – containing MDSearchBar instance and new text value.

Updates the text in the text input field to match the new text property value.