Tabs

See also

Material Design spec, Tabs

Tabs organize content across different screens, data sets, and other interactions.

Note

Module provides tabs in the form of icons or text.

Usage

To create a tab, you must create a new class that inherits from the MDTabsBase class and the Kivy container, in which you will create content for the tab.

class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''

<Tab>

    MDLabel:
        text: root.content_text
        pos_hint: {"center_x": .5, "center_y": .5}

All tabs must be contained inside a MDTabs widget:

Root:

    MDTabs:

        Tab:
            title: "Tab 1"
            content_text: f"This is an example text for {self.title}"

        Tab:
            title: "Tab 2"
            content_text: f"This is an example text for {self.title}"

        ...

Example with tab icon

Declarative KV and imperative python stylesDeclarative python styles

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsBase
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.icon_definitions import md_icons

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "Example Tabs"

    MDTabs:
        id: tabs
        on_tab_switch: app.on_tab_switch(*args)


<Tab>

    MDIconButton:
        id: icon
        icon: root.icon
        icon_size: "48sp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''


class Example(MDApp):
    icons = list(md_icons.keys())[15:30]

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        return Builder.load_string(KV)

    def on_start(self):
        for tab_name in self.icons:
            self.root.ids.tabs.add_widget(Tab(icon=tab_name))

    def on_tab_switch(
        self, instance_tabs, instance_tab, instance_tab_label, tab_text
    ):
        '''
        Called when switching tabs.

        :type instance_tabs: <kivymd.uix.tab.MDTabs object>;
        :param instance_tab: <__main__.Tab object>;
        :param instance_tab_label: <kivymd.uix.tab.MDTabsLabel object>;
        :param tab_text: text or name icon of tab;
        '''

        count_icon = instance_tab.icon  # get the tab icon
        print(f"Welcome to {count_icon}' tab'")


Example().run()

Example with tab text

Note

The MDTabsBase class has an icon parameter and, by default, tries to find the name of the icon in the file kivymd/icon_definitions.py.

If the name of the icon is not found, the class will send a message stating that the icon could not be found.

if the tab has no icon, title or tab_label_text, the class will raise a ValueError.

Declarative KV and imperative python stylesDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "Example Tabs"

    MDTabs:
        id: tabs
        on_tab_switch: app.on_tab_switch(*args)


<Tab>

    MDLabel:
        id: label
        text: "Tab 0"
        halign: "center"
'''


class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''


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

    def on_start(self):
        for i in range(20):
            self.root.ids.tabs.add_widget(Tab(title=f"Tab {i}"))

    def on_tab_switch(
        self, instance_tabs, instance_tab, instance_tab_label, tab_text
    ):
        '''Called when switching tabs.

        :type instance_tabs: <kivymd.uix.tab.MDTabs object>;
        :param instance_tab: <__main__.Tab object>;
        :param instance_tab_label: <kivymd.uix.tab.MDTabsLabel object>;
        :param tab_text: text or name icon of tab;
        '''

        instance_tab.ids.label.text = tab_text


Example().run()

Example with tab icon and text

Declarative KV and imperative python stylesDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsBase
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.icon_definitions import md_icons

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "Example Tabs"

    MDTabs:
        id: tabs
'''


class Tab(MDFloatLayout, MDTabsBase):
    pass


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

    def on_start(self):
        for name_tab in list(md_icons.keys())[15:30]:
            self.root.ids.tabs.add_widget(Tab(icon=name_tab, title=name_tab))


Example().run()

Dynamic tab management

Declarative KV and imperative python stylesDeclarative python style

from kivy.lang import Builder

from kivymd.uix.scrollview import MDScrollView
from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsBase

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "Example Tabs"

    MDTabs:
        id: tabs


<Tab>

    MDList:

        MDBoxLayout:
            adaptive_height: True

            MDFlatButton:
                text: "ADD TAB"
                on_release: app.add_tab()

            MDFlatButton:
                text: "REMOVE LAST TAB"
                on_release: app.remove_tab()

            MDFlatButton:
                text: "GET TAB LIST"
                on_release: app.get_tab_list()
'''


class Tab(MDScrollView, MDTabsBase):
    '''Class implementing content for a tab.'''


class Example(MDApp):
    index = 0

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        return Builder.load_string(KV)

    def on_start(self):
        self.add_tab()

    def get_tab_list(self):
        '''Prints a list of tab objects.'''

        print(self.root.ids.tabs.get_tab_list())

    def add_tab(self):
        self.index += 1
        self.root.ids.tabs.add_widget(Tab(title=f"{self.index} tab"))

    def remove_tab(self):
        if self.index > 1:
            self.index -= 1
        self.root.ids.tabs.remove_widget(
            self.root.ids.tabs.get_tab_list()[-1]
        )


Example().run()

Use on_ref_press method

You can use markup for the text of the tabs and use the on_ref_press method accordingly:

Declarative KV and imperative python stylesDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.font_definitions import fonts
from kivymd.uix.tab import MDTabsBase
from kivymd.icon_definitions import md_icons

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "Example Tabs"

    MDTabs:
        id: tabs
        on_ref_press: app.on_ref_press(*args)


<Tab>

    MDIconButton:
        id: icon
        icon: app.icons[0]
        icon_size: "48sp"
        pos_hint: {"center_x": .5, "center_y": .5}
'''


class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''


class Example(MDApp):
    icons = list(md_icons.keys())[15:30]

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        return Builder.load_string(KV)

    def on_start(self):
        for name_tab in self.icons:
            self.root.ids.tabs.add_widget(
                Tab(
                    title=f"[ref={name_tab}][font={fonts[-1]['fn_regular']}]{md_icons['close']}[/font][/ref]  {name_tab}"
                )
            )

    def on_ref_press(
        self,
        instance_tabs,
        instance_tab_label,
        instance_tab,
        instance_tab_bar,
        instance_carousel,
    ):
        '''
        The method will be called when the ``on_ref_press`` event
        occurs when you, for example, use markup text for tabs.

        :param instance_tabs: <kivymd.uix.tab.MDTabs object>
        :param instance_tab_label: <kivymd.uix.tab.MDTabsLabel object>
        :param instance_tab: <__main__.Tab object>
        :param instance_tab_bar: <kivymd.uix.tab.MDTabsBar object>
        :param instance_carousel: <kivymd.uix.tab.MDTabsCarousel object>
        '''

        # Removes a tab by clicking on the close icon on the left.
        for instance_tab in instance_carousel.slides:
            if instance_tab.title == instance_tab_label.text:
                instance_tabs.remove_widget(instance_tab_label)
                break


Example().run()

Switching the tab by name

Declarative KV and imperative python stylesDeclarative python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.icon_definitions import md_icons
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase

KV = '''
MDBoxLayout:
    orientation: "vertical"

    MDTopAppBar:
        title: "Example Tabs"

    MDTabs:
        id: tabs


<Tab>

    MDBoxLayout:
        orientation: "vertical"
        pos_hint: {"center_x": .5, "center_y": .5}
        adaptive_size: True
        spacing: dp(48)

        MDIconButton:
            id: icon
            icon: "arrow-right"
            icon_size: "48sp"
            on_release: app.switch_tab_by_name()

        MDIconButton:
            id: icon2
            icon: "page-next"
            icon_size: "48sp"
            on_release: app.switch_tab_by_object()
'''


class Tab(MDFloatLayout, MDTabsBase):
    '''Class implementing content for a tab.'''


class Example(MDApp):
    icons = list(md_icons.keys())[15:30]

    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.theme_cls.primary_palette = "Orange"
        self.iter_list_names = iter(list(self.icons))
        return Builder.load_string(KV)

    def on_start(self):
        for name_tab in list(self.icons):
            self.root.ids.tabs.add_widget(Tab(tab_label_text=name_tab))
        self.iter_list_objects = iter(list(self.root.ids.tabs.get_tab_list()))

    def switch_tab_by_object(self):
        try:
            x = next(self.iter_list_objects)
            print(f"Switch slide by object, next element to show: [{x}]")
            self.root.ids.tabs.switch_tab(x)
        except StopIteration:
            # reset the iterator an begin again.
            self.iter_list_objects = iter(list(self.root.ids.tabs.get_tab_list()))
            self.switch_tab_by_object()

    def switch_tab_by_name(self):
        '''Switching the tab by name.'''

        try:
            x = next(self.iter_list_names)
            print(f"Switch slide by name, next element to show: [{x}]")
            self.root.ids.tabs.switch_tab(x)
        except StopIteration:
            # Reset the iterator an begin again.
            self.iter_list_names = iter(list(self.icons))
            self.switch_tab_by_name()


Example().run()

API - kivymd.uix.tab.tab

class kivymd.uix.tab.tab.MDTabsBase(*args, **kwargs)

This class allow you to create a tab. You must create a new class that inherits from MDTabsBase. In this way you have total control over the views of your tabbed panel.

icon

This property will set the Tab’s Label Icon.

icon is an StringProperty and defaults to ‘’.

title_icon_mode

This property sets the mode in wich the tab’s title and icon are shown.

title_icon_mode is an OptionProperty and defaults to ‘Lead’.

title

This property will set the Name of the tab.

Note

As a side note.

All tabs have set markup = True. Thanks to this, you can use the kivy markup language to set a colorful and fully customizable tabs titles.

Warning

The material design requires that every title label is written in capital letters, because of this, the string.upper() will be applied to it’s contents.

title is an StringProperty and defaults to ‘’.

title_is_capital

This value controls wether if the title property should be converted to capital letters.

title_is_capital is an BooleanProperty and defaults to True.

tab_label_text

This property is the actual title’s Label of the tab. use the property icon and title to set this property correctly.

This property is kept public for specific and backward compatibility purposes.

tab_label_text is an StringProperty and defaults to ‘’.

tab_label

It is the label object reference of the tab.

tab_label is an ObjectProperty and defaults to None.

tab_label_font_style

tab_label_font_style is an AliasProperty that behavies similar to an OptionProperty.

This property’s behavior allows the developer to use any new label style registered to the app.

This property will affect the Tab’s Title Label widget.

update_label_text(self, instance_user_tab, text_tab: str)

class kivymd.uix.tab.tab.MDTabs(*args, **kwargs)

Tabs class. You can use this class to create your own tabbed panel.

For more information, see in the DeclarativeBehavior and ThemableBehavior and SpecificBackgroundColorBehavior and AnchorLayout classes documentation.

Events:

on_tab_switch

Called when switching tabs.

on_slide_progress

Called while the slide is scrolling.

on_ref_press

The method will be called when the on_ref_press event occurs when you, for example, use markup text for tabs.

tab_bar_height

Height of the tab bar.

tab_bar_height is an NumericProperty and defaults to ‘48dp’.

tab_padding

Padding of the tab bar.

tab_padding is an ListProperty and defaults to [0, 0, 0, 0].

tab_indicator_anim

Tab indicator animation. If you want use animation set it to True.

tab_indicator_anim is an BooleanProperty and defaults to False.

tab_indicator_height

Height of the tab indicator.

tab_indicator_height is an NumericProperty and defaults to ‘2dp’.

tab_indicator_type

Type of tab indicator. Available options are: ‘line’, ‘fill’, ‘round’, ‘line-rect’ and ‘line-round’.

tab_indicator_type is an OptionProperty and defaults to ‘line’.

tab_hint_x

This option affects the size of each child. if it’s True, the size of each tab will be ignored and will use the size available by the container.

tab_hint_x is an BooleanProperty and defaults to False.

anim_duration

Duration of the slide animation.

anim_duration is an NumericProperty and defaults to 0.2.

anim_threshold

Animation threshold allow you to change the tab indicator animation effect.

anim_threshold is an BoundedNumericProperty and defaults to 0.8.

allow_stretch

If True, the tab will update dynamically (if tab_hint_x is True) to it’s content width, and wrap any text if the widget is wider than “360dp”.

If False, the tab won’t update to it’s maximum texture width. this means that the fixed_tab_label_width will be used as the label width. this will wrap any text inside to fit the fixed value.

allow_stretch is an BooleanProperty and defaults to True.

fixed_tab_label_width

If allow_stretch is False, the class will set this value as the width to all the tabs title label.

fixed_tab_label_width is an NumericProperty and defaults to 140dp.

background_color

Background color of tabs in (r, g, b, a) or string format.

background_color is an ColorProperty and defaults to None.

underline_color

Underline color of tabs in (r, g, b, a) or string format.

underline_color is an ColorProperty and defaults to [0, 0, 0, 0].

text_color_normal

Text color in (r, g, b, a) or string format of the label when it is not selected.

text_color_normal is an ColorProperty and defaults to None.

text_color_active

Text color in (r, g, b, a) or string format of the label when it is selected.

text_color_active is an ColorProperty and defaults to None.

shadow_softness

See kivymd.uix.behaviors.CommonElevationBehavior.shadow_softness attribute.

New in version 1.1.0.

shadow_softness is an NumericProperty and defaults to 12.

shadow_color

See kivymd.uix.behaviors.CommonElevationBehavior.shadow_color attribute.

New in version 1.1.0.

shadow_color is an ColorProperty and defaults to [0, 0, 0, 0.6].

shadow_offset

See kivymd.uix.behaviors.CommonElevationBehavior.shadow_offset attribute.

New in version 1.1.0.

shadow_offset is an ListProperty and defaults to [0, 0].

elevation

See kivymd.uix.behaviors.CommonElevationBehavior.elevation attribute.

elevation is an NumericProperty and defaults to 0.

indicator_color

Color indicator in (r, g, b, a) or string format.

indicator_color is an ColorProperty and defaults to None.

lock_swiping

If True - disable switching tabs by swipe.

lock_swiping is an BooleanProperty and defaults to False.

font_name

Font name for tab text.

font_name is an StringProperty and defaults to ‘Roboto’.

ripple_duration

Ripple duration when long touching to tab.

ripple_duration is an NumericProperty and defaults to 2.

no_ripple_effect

Whether to use the ripple effect when tapping on a tab.

no_ripple_effect is an BooleanProperty and defaults to True.

title_icon_mode

This property sets the mode in wich the tab’s title and icon are shown.

title_icon_mode is an OptionProperty and defaults to ‘Lead’.

force_title_icon_mode

If this property is se to True, it will force the class to update every tab inside the scroll view to the current title_icon_mode

force_title_icon_mode is an BooleanProperty and defaults to True.

update_icon_color(self, instance_theme_manager: ThemeManager, name_theme_style_name_palette: str)

Called when the app’s color scheme or style has changed (dark theme/light theme).

switch_tab(self, name_tab: MDTabsLabel | str, search_by='text')

This method switch between tabs name_tab can be either a String or a MDTabsBase.

search_by will look up through the properties of every tab.

If the value doesnt match, it will raise a ValueError.

Search_by options:

text : will search by the raw text of the label (tab_label_text) icon : will search by the icon property title : will search by the title property

get_tab_list(self)

Returns a list of MDTabsLabel objects.

get_slides(self)

Returns a list of user tab objects.

get_current_tab(self)

Returns current tab object.

New in version 1.0.0.

add_widget(self, widget, index=0, canvas=None)

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.

New 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.

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

remove_widget(self, 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)

on_slide_progress(self, *args)

This event is deployed every available frame while the tab is scrolling.

on_carousel_index(self, instance_tabs_carousel, index: int)

Called when the Tab index have changed.

This event is deployed by the built in carousel of the class.

on_ref_press(self, *args)

This event will be launched every time the user press a markup enabled label with a link or reference inside.

on_tab_switch(self, *args)

This event is launched every time the current tab is changed.

on_size(self, instance_tab, size: list)

Called when the application screen is resized.