Tabs#

#

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

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-preview.png
  • 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

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-types.png
  1. Primary tabs

  2. Secondary tabs

Usage primary tabs#

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

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):
        super().on_start()
        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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-usage.png

Anatomy primary tabs#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-anatomy.png

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.

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):
        super().on_start()
        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#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-secondary-anatomy.png

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.

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):
        super().on_start()
        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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-scrollable-behavior.gif

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.

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):
        super().on_start()
        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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-fixed-behavior.png

Tap a tab#

Navigate to a tab by tapping on it.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-tap-a-tab-behavior.gif

Swipe within the content area#

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

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/tab-primary-swipe-within-content-area-behavior.gif

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):
        super().on_start()
        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#

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):
        super().on_start()
        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):
        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.

New in version 2.0.0.

For more information, see in the MDBadge class documentation.

class kivymd.uix.tab.tab.MDTabsCarousel(**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.

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

Implements an label for the MDTabsItem class.

For more information, see in the MDLabel class documentation.

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

New in version 2.0.0.

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

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

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

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

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

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

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

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

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

New in version 1.0.0.

Returns the carousel slide object (related content).

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

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.

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

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

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

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)
class kivymd.uix.tab.tab.MDTabsSecondary(*args, **kwargs)#

Tabs secondary class.

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