SegmentedButton

Added in version 1.2.0.

See also

Material Design spec, Segmented buttons

Segmented control

Segmented buttons help people select options, switch views, or sort elements.

• Segmented buttons can contain icons, label text, or both

• Two types: single-select and multi-select

• Use for simple choices between two to five items (for more items or complex choices, use chips)

1. Single-select segmented button

2. Multi-select segmented button

Anatomy

Icons

Icons may be used as labels by themselves or alongside text. If an icon is used without label text, it must clearly communicate the option it represents.

Use with text and icon

Declarative KV styleDeclarative python style

MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-python"

        MDSegmentButtonLabel:
            text: "Python"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-javascript"

        MDSegmentButtonLabel:
            text: "Java-Script"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-swift"

        MDSegmentButtonLabel:
            text: "Swift"

Use without text with an icon

Declarative KV styleDeclarative python style

MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-python"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-javascript"

    MDSegmentedButtonItem:

        MDSegmentButtonIcon:
            icon: "language-swift"

Use only text

Declarative KV styleDeclarative python style

MDSegmentedButton:

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Python"

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Java-Script"

    MDSegmentedButtonItem:

        MDSegmentButtonLabel:
            text: "Swift"

Multiselect

For multiple marking of elements, use the kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton.multiselect parameter:

MDSegmentedButton:
    multiselect: True

Type

Density can be used in denser UIs where space is limited. Density is only applied to the height. Each step down in density removes 4dp from the height.

from kivymd.uix.label import MDLabel
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.screen import MDScreen
from kivymd.uix.segmentedbutton import (
    MDSegmentedButton,
    MDSegmentedButtonItem,
    MDSegmentButtonLabel,
)
from kivymd.app import MDApp


class MyBox(MDBoxLayout):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        widgets = []
        for segment_type in ["large", "normal", "medium", "small"]:
            widgets.append(
                MDBoxLayout(
                    MDLabel(
                        text=f"Type '{segment_type}'",
                        adaptive_height=True,
                        bold=True,
                        pos_hint={"center_y": 0.5},
                        halign="center",
                    ),
                    MDSegmentedButton(
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Songs",
                            ),
                        ),
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Albums",
                            ),
                        ),
                        MDSegmentedButtonItem(
                            MDSegmentButtonLabel(
                                text="Podcasts",
                            ),
                        ),
                        type=segment_type,
                    ),
                    orientation="vertical",
                    spacing="12dp",
                    adaptive_height=True,
                )
            )
        self.widgets = widgets


class Example(MDApp):
    def build(self):
        return (
            MDScreen(
                MyBox(
                    orientation="vertical",
                    size_hint_x=.7,
                    adaptive_height=True,
                    spacing="24dp",
                    pos_hint={"center_x": .5, "center_y": .5},
                ),
                md_bg_color=self.theme_cls.backgroundColor
            )
        )


Example().run()

A practical example

Declarative Python style with KVDeclarative python style

import os

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

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout

import asynckivy
from faker import Faker

KV = '''
<UserCard>
    adaptive_height: True
    radius: dp(16)

    MDListItem:
        radius: dp(16)
        theme_bg_color: "Custom"
        md_bg_color: self.theme_cls.secondaryContainerColor

        MDListItemLeadingAvatar:
            source: root.album

        MDListItemHeadlineText:
            text: root.name

        MDListItemSupportingText:
            text: root.path_to_file


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        orientation: "vertical"
        padding: "12dp"
        spacing: "12dp"

        MDLabel:
            adaptive_height: True
            text: "Your downloads"
            font_style: "Display"
            role: "small"

        MDSegmentedButton:
            size_hint_x: 1

            MDSegmentedButtonItem:
                active: True
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Songs"

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Albums"

            MDSegmentedButtonItem:
                on_active: app.generate_card()

                MDSegmentButtonLabel:
                    text: "Podcasts"

        RecycleView:
            id: card_list
            viewclass: "UserCard"
            bar_width: 0

            RecycleBoxLayout:
                orientation: 'vertical'
                spacing: "16dp"
                padding: "16dp"
                default_size: None, dp(72)
                default_size_hint: 1, None
                size_hint_y: None
                height: self.minimum_height
'''


class UserCard(MDBoxLayout):
    name = StringProperty()
    path_to_file = StringProperty()
    album = StringProperty()


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

    def generate_card(self):
        async def generate_card():
            for i in range(10):
                await asynckivy.sleep(0)
                self.root.ids.card_list.data.append(
                    {
                        "name": fake.name(),
                        "path_to_file": f"{os.path.splitext(fake.file_path())[0]}.mp3",
                        "album": fake.image_url(),
                    }
                )

        fake = Faker()
        self.root.ids.card_list.data = []
        Clock.schedule_once(lambda x: asynckivy.start(generate_card()))


Example().run()

API break

1.2.0 version

MDSegmentedButton:
    on_marked: func(*args)

    MDSegmentedButtonItem:
        icon: ...
        text: ...

2.0.0 version

Declarative KV styleDeclarative python style

MDSegmentedButton:

    MDSegmentedButtonItem:
        on_active: func(*args)

        MDSegmentButtonIcon:
            icon: ...

        MDSegmentButtonLabel:
            text: ...

API - kivymd.uix.segmentedbutton.segmentedbutton

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButtonItem(*args, **kwargs)

Segment button item.

For more information see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and StateLayerBehavior and RelativeLayout and class documentation.

selected_color

Color of the marked segment.

Added in version 2.0.0.

selected_color is a ColorProperty and defaults to None.

md_bg_color_disabled

The background color in (r, g, b, a) or string format of the list item when the list item is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

active

Background color of an disabled segment.

active is an BooleanProperty and defaults to False.

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)

on_line_color(instance, value) → None

Fired when the values of line_color change.

on_active(instance, value) → None

Fired when the active value changes. Animates the marker icon for the element.

on_disabled(instance, value) → None

Fired when the disabled value changes.

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentedButton(*args, **kwargs)

Segment button panel.

For more information, see in the MDBoxLayout class documentation.

multiselect

Do I allow multiple segment selection.

multiselect is an BooleanProperty and defaults to False.

hiding_icon_transition

Name of the transition hiding the current icon.

hiding_icon_transition is a StringProperty and defaults to ‘linear’.

hiding_icon_duration

Duration of hiding the current icon.

hiding_icon_duration is a NumericProperty and defaults to 1.

opening_icon_transition

The name of the transition that opens a new icon of the “marked” type.

opening_icon_transition is a StringProperty and defaults to ‘linear’.

opening_icon_duration

The duration of opening a new icon of the “marked” type.

opening_icon_duration is a NumericProperty and defaults to 0.1.

selected_segments

The list of MDSegmentedButtonItem objects that are currently marked.

selected_segments is a ListProperty and defaults to [].

type

Density can be used in denser UIs where space is limited. Density is only applied to the height. Each step down in density removes ‘4dp’ from the height.

Added in version 2.0.0.

Available options are: ‘large’, ‘normal’, ‘medium’, ‘small’.

type is an OptionProperty and defaults to ‘large’.

selected_icon_color

Color in (r, g, b, a) or string format of the icon of the marked segment.

Added in version 2.0.0.

selected_icon_color is a ColorProperty and defaults to None.

get_marked_items() → list

Returns a list of active item objects.

get_items() → list

Returns a list of item objects.

adjust_segment_radius(*args) → None

Rounds off the first and last elements.

mark_item(segment_item: MDSegmentedButtonItem) → None

Fired when a segment element is clicked (on_release event).

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)

remove_widget(widget, *args, **kwargs)

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.segmentedbutton.segmentedbutton.MDSegmentButtonIcon(*args, **kwargs)

Implements a icon for MDSegmentedButtonItem class.

Added in version 2.0.0.

For more information, see in the MDIcon class documentation.

class kivymd.uix.segmentedbutton.segmentedbutton.MDSegmentButtonLabel(*args, **kwargs)

Implements a label for MDSegmentedButtonItem class.

Added in version 2.0.0.

For more information, see in the MDLabel class documentation.