Tabs

See also

Material Design spec, Tabs

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

• Use tabs to group content into helpful categories

• Two types: primary and secondary

• Tabs can horizontally scroll, so a UI can have as many tabs as needed

• Place tabs next to each other as peers

1. Primary tabs

2. Secondary tabs

Usage primary tabs

Primary tabs should be used when just one set of tabs are needed.

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import (
    MDTabsItem,
    MDTabsItemIcon,
    MDTabsItemText,
    MDTabsBadge,
)

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        for tab_icon, tab_name in {
            "airplane": "Flights",
            "treasure-chest": "Trips",
            "compass-outline": "Explore",
        }.items():
            if tab_icon == "treasure-chest":
                self.root.ids.tabs.add_widget(
                    MDTabsItem(
                        MDTabsItemIcon(
                            MDTabsBadge(
                                text="99",
                            ),
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                    )
                )
            else:
                self.root.ids.tabs.add_widget(
                    MDTabsItem(
                        MDTabsItemIcon(
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                    )
                )
            self.root.ids.tabs.switch_tab(icon="airplane")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

Anatomy primary tabs

Usage secondary tabs

Secondary tabs are necessary when a screen requires more than one level of tabs. These tabs use a simpler style of indicator, but their function is identical to primary tabs.

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import (
    MDTabsItemIcon,
    MDTabsItemText,
    MDTabsBadge, MDTabsItemSecondary,
)

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTabsSecondary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        for tab_icon, tab_name in {
            "airplane": "Flights",
            "treasure-chest": "Trips",
            "compass-outline": "Explore",
        }.items():
            if tab_icon == "treasure-chest":
                self.root.ids.tabs.add_widget(
                    MDTabsItemSecondary(
                        MDTabsItemIcon(
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                        MDTabsBadge(
                            text="5",
                        ),
                    )
                )
            else:
                self.root.ids.tabs.add_widget(
                    MDTabsItemSecondary(
                        MDTabsItemIcon(
                            icon=tab_icon,
                        ),
                        MDTabsItemText(
                            text=tab_name,
                        ),
                    )
                )
        self.root.ids.tabs.switch_tab(icon="airplane")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

Anatomy secondary tabs

Related content

Use tabs to group related content, not sequential content.

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.label import MDLabel
from kivymd.uix.tab import (
    MDTabsItemIcon,
    MDTabsItemText,
    MDTabsItem,
)

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .6

        MDDivider:

        MDTabsCarousel:
            id: related_content_container
            size_hint_y: None
            height: dp(320)
'''


class Example(MDApp):
    def on_start(self):
        for tab_icon, tab_name in {
            "airplane": "Flights",
            "treasure-chest": "Trips",
            "compass-outline": "Explore",
        }.items():
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemIcon(
                        icon=tab_icon,
                    ),
                    MDTabsItemText(
                        text=tab_name,
                    ),
                )
            )
            self.root.ids.related_content_container.add_widget(
                MDLabel(
                    text=tab_name,
                    halign="center",
                )
            )
            self.root.ids.tabs.switch_tab(icon="airplane")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

Behaviors

Scrollable tabs

When a set of tabs cannot fit on screen, use scrollable tabs. Scrollable tabs can use longer text labels and a larger number of tabs. They are best used for browsing on touch interfaces.

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsItemText, MDTabsItem

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .6
        allow_stretch: False
        label_only: True

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        for tab_name in [
            "Moscow",
            "Saint Petersburg",
            "Novosibirsk",
            "Yekaterinburg",
            "Kazan",
            "Nizhny Novgorod",
            "Chelyabinsk",
        ]:
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemText(
                        text=tab_name,
                    ),
                )
            )
        self.root.ids.tabs.switch_tab(text="Moscow")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

Fixed tabs

Fixed tabs display all tabs in a set simultaneously. They are best for switching between related content quickly, such as between transportation methods in a map. To navigate between fixed tabs, tap an individual tab, or swipe left or right in the content area.

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsItemText, MDTabsItem

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTabsPrimary:
        id: tabs
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .6
        allow_stretch: True
        label_only: True

        MDDivider:
'''


class Example(MDApp):
    def on_start(self):
        for tab_name in [
            "Moscow", "Saint Petersburg", "Novosibirsk"
        ]:
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemText(
                        text=tab_name,
                    ),
                )
            )
        self.root.ids.tabs.switch_tab(text="Moscow")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

Tap a tab

Navigate to a tab by tapping on it.

Swipe within the content area

To navigate between tabs, users can swipe left or right within the content area.

Switching tab

You can switch tabs by icon name, by tab name, and by tab objects:

instance_tabs.switch_tab(icon="airplane")

instance_tabs.switch_tab(text="Airplane")

instance_tabs.switch_tab(
    instance=instance_tabs_item  # MDTabsItem
)

API break

1.2.0 version

from kivy.lang import Builder

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

KV = '''
MDBoxLayout:

    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):
        return Builder.load_string(KV)

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


Example().run()

2.0.0 version

Declarative KV styleDeclarative Python style

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.icon_definitions import md_icons
from kivymd.uix.label import MDIcon
from kivymd.uix.tab import MDTabsItem, MDTabsItemIcon
from kivymd.uix.tab.tab import MDTabsItemText

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDTabsPrimary:
        id: tabs
        allow_stretch: False
        pos_hint: {"center_x": .5, "center_y": .5}

        MDDivider:

        MDTabsCarousel:
            id: related_content
            size_hint_y: None
            height: root.height - tabs.ids.tab_scroll.height
'''


class Example(MDApp):
    def on_start(self):
        for name_tab in list(md_icons.keys())[15:30]:
            self.root.ids.tabs.add_widget(
                MDTabsItem(
                    MDTabsItemIcon(
                        icon=name_tab,
                    ),
                    MDTabsItemText(
                        text=name_tab,
                    ),
                )
            )
            self.root.ids.related_content.add_widget(
                MDIcon(
                    icon=name_tab,
                    pos_hint={"center_x": 0.5, "center_y": 0.5},
                )
            )
            self.root.ids.tabs.switch_tab(icon="airplane")

    def build(self):
        self.theme_cls.primary_palette = "Olive"
        return Builder.load_string(KV)


Example().run()

API - kivymd.uix.tab.tab

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

Implements an badge for secondary tabs.

Added in version 2.0.0.

For more information, see in the MDBadge class documentation.

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

Implements a carousel for user-generated content.

For more information, see in the Carousel class documentation.

lock_swiping

If True - disable switching tabs by swipe.

lock_swiping is an BooleanProperty and defaults to False.

on_touch_move(touch) → str | bool | None

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

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)

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

Implements an label for the MDTabsItem class.

For more information, see in the MDLabel class documentation.

Added in version 2.0.0.

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

Implements an icon for the MDTabsItem class.

For more information, see in the MDIcon class documentation.

Added in version 2.0.0.

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

Implements a item with an icon and text for MDTabsPrimary class.

Added in version 2.0.0.

For more information, see in the MDTabsItemBase and BoxLayout classes 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)

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

Tabs primary class.

Changed in version 2.0.0: Rename from MDTabs to MDTabsPrimary class.

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

Events:

on_tab_switch

Fired when switching tabs.

md_bg_color

The background color of the widget.

md_bg_color is an ColorProperty and defaults to None.

label_only

Tabs with a label only or with an icon and a label.

Added in version 2.0.0.

label_only is an BooleanProperty and defaults to False.

allow_stretch

Whether to stretch tabs to the width of the panel.

allow_stretch is an BooleanProperty and defaults to True.

lock_swiping

If True - disable switching tabs by swipe.

lock_swiping is an BooleanProperty and defaults to False.

anim_duration

Duration of the slide animation.

anim_duration is an NumericProperty and defaults to 0.2.

indicator_anim

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

Changed in version 2.0.0: Rename from tab_indicator_anim to indicator_anim attribute.

indicator_anim is an BooleanProperty and defaults to True.

indicator_radius

Radius of the tab indicator.

Added in version 2.0.0.

indicator_radius is an VariableListProperty and defaults to [dp(2), dp(2), 0, 0].

indicator_height

Height of the tab indicator.

Changed in version 2.0.0: Rename from tab_indicator_height to indicator_height attribute.

indicator_height is an NumericProperty and defaults to ‘4dp’.

indicator_duration

The duration of the animation of the indicator movement when switching tabs.

Added in version 2.0.0.

indicator_duration is an NumericProperty and defaults to 0.5.

indicator_transition

The transition name of animation of the indicator movement when switching tabs.

Added in version 2.0.0.

indicator_transition is an StringProperty and defaults to `’out_expo’.

last_scroll_x

Is the carousel reference of the next tab/slide. When you go from ‘Tab A’ to ‘Tab B’, ‘Tab B’ will be the target tab/slide of the carousel.

last_scroll_x is an AliasProperty.

target

It is the carousel reference of the next tab / slide. When you go from ‘Tab A’ to ‘Tab B’, ‘Tab B’ will be the target tab / slide of the carousel.

target is an ObjectProperty and default to None.

indicator

It is the SmoothRoundedRectangle instruction reference of the tab indicator.

indicator is an AliasProperty.

get_last_scroll_x()

get_rect_instruction()

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)

do_autoscroll_tabs(instance: MDTabsItem, value: float) → None

Automatically scrolls the list of tabs when swiping the carousel slide (related content).

Changed in version 2.0.0: Rename from tab_bar_autoscroll to do_autoscroll_tabs method.

android_animation(instance: MDTabsCarousel, offset: float) → None

Fired when swiping a carousel slide (related content).

update_indicator(x: float = 0.0, w: float = 0.0, instance: MDTabsItem = None) → None

Update position and size of the indicator.

switch_tab(instance: MDTabsItem = None, text: str = '', icon: str = '') → None

Switches tabs by tab object/tab text/tab icon name.

set_active_item(item: MDTabsItem) → None

Sets the active tab item.

get_tabs_list() → list

Returns a list of MDTabsItem objects.

Changed in version 2.0.0: Rename from get_tab_list to get_tabs_list method.

get_slides_list() → list

Returns a list of user tab objects.

Changed in version 2.0.0: Rename from get_slides to get_slides_list method.

get_current_tab() → MDTabsItem

Returns current tab object.

Added in version 1.0.0.

get_current_related_content() → kivy.uix.widget.Widget

Returns the carousel slide object (related content).

Added in version 2.0.0.

on_tab_switch(*args) → None

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

on_slide_progress(*args) → None

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

on_carousel_index(instance: MDTabsCarousel, value: int) → None

Fired when the Tab index have changed. This event is deployed by the builtin carousel of the class.

on_size(instance, size) → None

Fired when the application screen size changes.

recalculate_tab_widths() → None

Recalculates and updates the width of each tab in the tab bar.

This method ensures that all tabs are evenly distributed across the available horizontal space when allow_stretch is enabled. It is automatically called after a new tab is added.

If no tabs are present, the method exits without making changes.

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

Implements a item with an icon and text for MDTabsSecondary class.

Added in version 2.0.0.

For more information, see in the MDTabsItemBase and AnchorLayout classes 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)

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

Tabs secondary class.

Added in version 2.0.0.

For more information, see in the MDTabsPrimary class documentation.

indicator_radius

Radius of the tab indicator.

indicator_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

indicator_height

Height of the tab indicator.

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