SegmentedButton

A segmented button control.

Inherits: LayoutControl

Properties

• allow_empty_selection(bool) –

  A boolean value that indicates if having no selected segments is allowed.

• allow_multiple_selection(bool) –

  A boolean value that indicates if multiple segments can be selected at one time.

• direction(Axis | None) –

  The orientation of the button's segments.

• padding(PaddingValue | None) –

  Defines the button's size and padding. If specified, the button expands to fill its

• segments(list[Segment]) –

  The segments of this button.

• selected(list[str]) –

  A set of Segment.values that indicate which segments are selected. It is updated

• selected_icon(IconDataOrControl | None) –

  An Icon control that is used to indicate a segment is selected.

• show_selected_icon(bool) –

  A boolean value that indicates if the selected_icon is displayed on the

• style(ButtonStyle | None) –

  Customizes this button's appearance.

Events

• on_change(ControlEventHandler[SegmentedButton] | None) –

  Called when the selection changes.

Examples

Live example

Basic Example

import flet as ft


def main(page: ft.Page):
    def handle_selection_change(e: ft.Event[ft.SegmentedButton]):
        print(e)

    page.add(
        ft.SegmentedButton(
            on_change=handle_selection_change,
            selected_icon=ft.Icon(ft.Icons.CHECK_SHARP),
            selected=["1"],
            allow_empty_selection=True,
            allow_multiple_selection=True,
            segments=[
                ft.Segment(
                    value="1",
                    label=ft.Text("1"),
                    icon=ft.Icon(ft.Icons.LOOKS_ONE),
                ),
                ft.Segment(
                    value="2",
                    label=ft.Text("2"),
                    icon=ft.Icon(ft.Icons.LOOKS_TWO),
                ),
                ft.Segment(
                    value="3",
                    label=ft.Text("3"),
                    icon=ft.Icon(ft.Icons.LOOKS_3),
                ),
                ft.Segment(
                    value="4",
                    label=ft.Text("4"),
                    icon=ft.Icon(ft.Icons.LOOKS_4),
                ),
            ],
        ),
        ft.SegmentedButton(
            on_change=handle_selection_change,
            selected_icon=ft.Icon(ft.Icons.ONETWOTHREE),
            selected=["2"],
            allow_multiple_selection=False,
            segments=[
                ft.Segment(
                    value="1",
                    label=ft.Text("1"),
                    icon=ft.Icon(ft.Icons.LOOKS_ONE),
                ),
                ft.Segment(
                    value="2",
                    label=ft.Text("2"),
                    icon=ft.Icon(ft.Icons.LOOKS_TWO),
                ),
                ft.Segment(
                    value="3",
                    label=ft.Text("3"),
                    icon=ft.Icon(ft.Icons.LOOKS_3),
                ),
                ft.Segment(
                    value="4",
                    label=ft.Text("4"),
                    icon=ft.Icon(ft.Icons.LOOKS_4),
                ),
            ],
        ),
    )


ft.run(main)

Properties

allow_empty_selection class-attribute instance-attribute

allow_empty_selection: bool = False

A boolean value that indicates if having no selected segments is allowed.

If True, then it is acceptable for none of the segments to be selected and also that selected can be empty.

If False (the default), there must be at least one segment selected. If the user taps on the only selected segment it will not be deselected, and on_change will not be called.

Raises:

• ValueError –

  If selected is empty while allow_empty_selection is False.

allow_multiple_selection class-attribute instance-attribute

allow_multiple_selection: bool = False

A boolean value that indicates if multiple segments can be selected at one time.

If True, more than one segment can be selected. When selecting a segment, the other selected segments will stay selected. Selecting an already selected segment will unselect it.

If False (the default), only one segment may be selected at a time. When a segment is selected, any previously selected segment will be unselected.

Raises:

• ValueError –

  If selected has more than one item while allow_multiple_selection is False.

direction class-attribute instance-attribute

direction: Axis | None = None

The orientation of the button's segments.

Defaults to Axis.HORIZONTAL.

padding class-attribute instance-attribute

padding: PaddingValue | None = None

Defines the button's size and padding. If specified, the button expands to fill its parent's space with this padding.

When None, the button adopts its intrinsic content size.

segments instance-attribute

segments: list[Segment]

The segments of this button.

Raises:

• ValueError –

  If segments is empty or does not have at least one visible Segment.

selected class-attribute instance-attribute

selected: list[str] = field(default_factory=list)

A set of Segment.values that indicate which segments are selected. It is updated when the user (un)selects a segment.

Raises:

• ValueError –

  If selected violates the constraints defined by allow_empty_selection or allow_multiple_selection.

selected_icon class-attribute instance-attribute

selected_icon: IconDataOrControl | None = None

An Icon control that is used to indicate a segment is selected.

If show_selected_icon is True then for selected segments this icon will be shown before the Segment.label, replacing the Segment.icon if it is specified.

Defaults to an Icon with the CHECK icon.

show_selected_icon class-attribute instance-attribute

show_selected_icon: bool = True

A boolean value that indicates if the selected_icon is displayed on the selected segments.

If True, the selected_icon will be displayed at the start of the selected segments.

If False, then the selected_icon is not used and will not be displayed on selected segments.

style class-attribute instance-attribute

style: ButtonStyle | None = None

Customizes this button's appearance.

Events

on_change class-attribute instance-attribute

on_change: ControlEventHandler[SegmentedButton] | None = (
    None
)

Called when the selection changes.

The data property of the event handler argument contains a list of strings identifying the selected segments.

Inherits: Control

A segment for a SegmentedButton.

Properties

• icon(IconDataOrControl | None) –

  The icon (typically an Icon) to be

• label(StrOrControl | None) –

  The label (usually a Text) to be

• value(str) –

  Used to identify the Segment.

Properties

icon class-attribute instance-attribute

icon: IconDataOrControl | None = None

The icon (typically an Icon) to be displayed in the segment.

label class-attribute instance-attribute

label: StrOrControl | None = None

The label (usually a Text) to be displayed in the segment.

Raises:

• ValueError –

  If neither icon nor label is set.

value instance-attribute

value: str

Used to identify the Segment.