ExpansionTile

A single-line ListTile with an expansion arrow icon that expands or collapses the tile to reveal or hide its controls.

Example:

ft.ExpansionTile(
    width=400,
    title="Account",
    subtitle="Manage profile and security",
    expanded=True,
    controls=[
        ft.ListTile(title=ft.Text("Profile")),
        ft.ListTile(title=ft.Text("Security")),
    ],
)

Inherits: LayoutControl, AdaptiveControl

Properties

affinity - Typically used to force the expansion arrow icon to the tile's leading or trailing edge.
animation_style - Defines the animation style (curve and duration) for this tile's expansion and collapse.
bgcolor - The color to display behind the sublist when expanded.
clip_behavior - Defines how the content of this tile is clipped.
collapsed_bgcolor - Defines the background color of this tile when the sublist is collapsed (expanded is False).
collapsed_icon_color - The icon color of this tile's expansion arrow icon when the sublist is collapsed (expanded is False).
collapsed_shape - The tile's border shape when the sublist is collapsed.
collapsed_text_color - The color of this tile's titles when the sublist is collapsed (expanded is False).
controls - The controls to be displayed when this tile expanded.
controls_padding - Defines the padding around the controls.
dense - Whether this list tile is part of a vertically dense list.
enable_feedback - Whether detected gestures should provide acoustic and/or haptic feedback.
expanded - The expansion state of this tile.
expanded_alignment - Defines the alignment of controls, which are arranged in a column when the tile is expanded.
expanded_cross_axis_alignment - Defines the alignment of each child control within controls when the tile is expanded.
icon_color - The icon color of this tile's expansion arrow icon when the sublist is expanded.
leading - A Control to display before the title.
maintain_state - A boolean value which defines whether the state of the controls is maintained when this tile expanded and collapses.
min_tile_height - The minimum height of this tile.
shape - The border shape of this tile when the sublist is expanded.
show_trailing_icon - Whether this tile should build/show a default trailing icon, if trailing is None.
subtitle - Additional content displayed below the title.
text_color - The color of this tile's titles when the sublist is expanded.
tile_padding - Defines the tile's padding.
title - A Control to display as primary content of this tile.
trailing - A Control to display after the title.
visual_density - Defines how compact this tile's layout will be.

Events

on_change - Called when a user clicks or taps the list tile.

Examples

Live example

Basic Example

import flet as ft


def main(page: ft.Page):
    page.theme_mode = ft.ThemeMode.LIGHT
    page.spacing = 0
    page.padding = 0

    def handle_tile_change(e: ft.Event[ft.ExpansionTile]):
        page.show_dialog(
            ft.SnackBar(
                duration=1000,
                content=ft.Text(
                    value=(
                        f"ExpansionTile was "
                        f"{'expanded' if e.data == 'true' else 'collapsed'}"
                    )
                ),
            )
        )
        if e.control.trailing:
            e.control.trailing.icon = (
                ft.Icons.ARROW_DROP_DOWN
                if e.control.trailing.icon == ft.Icons.ARROW_DROP_DOWN_CIRCLE
                else ft.Icons.ARROW_DROP_DOWN_CIRCLE
            )
            e.control.trailing.update()

    page.add(
        ft.SafeArea(
            content=ft.Column(
                spacing=0,
                controls=[
                    ft.ExpansionTile(
                        expanded=True,
                        title=ft.Text("ExpansionTile 1"),
                        subtitle=ft.Text("Trailing expansion arrow icon"),
                        affinity=ft.TileAffinity.PLATFORM,
                        maintain_state=True,
                        collapsed_text_color=ft.Colors.RED,
                        text_color=ft.Colors.RED,
                        controls=[
                            ft.ListTile(title=ft.Text("This is sub-tile number 1.1")),
                            ft.ListTile(title=ft.Text("This is sub-tile number 1.2")),
                        ],
                    ),
                    ft.ExpansionTile(
                        expanded=True,
                        title=ft.Text("ExpansionTile 2"),
                        subtitle=ft.Text("Custom expansion arrow icon"),
                        trailing=ft.Icon(ft.Icons.ARROW_DROP_DOWN),
                        collapsed_text_color=ft.Colors.GREEN,
                        text_color=ft.Colors.GREEN,
                        on_change=handle_tile_change,
                        controls=[
                            ft.ListTile(title=ft.Text("This is sub-tile number 2.1")),
                            ft.ListTile(title=ft.Text("This is sub-tile number 2.2")),
                        ],
                    ),
                    ft.ExpansionTile(
                        expanded=True,
                        title=ft.Text("ExpansionTile 3"),
                        subtitle=ft.Text("Leading expansion arrow icon"),
                        affinity=ft.TileAffinity.LEADING,
                        collapsed_text_color=ft.Colors.BLUE_800,
                        text_color=ft.Colors.BLUE_200,
                        controls=[
                            ft.ListTile(title=ft.Text("This is sub-tile number 3.1")),
                            ft.ListTile(title=ft.Text("This is sub-tile number 3.2")),
                        ],
                    ),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

Programmatic expansion/collapse

import flet as ft


def main(page: ft.Page):
    page.spacing = 20

    tile = ft.ExpansionTile(
        title=ft.Text("I am the title of this tile.", weight=ft.FontWeight.BOLD),
        subtitle=ft.Text("This is the subtitle."),
        affinity=ft.TileAffinity.LEADING,
        controls=[ft.Text("👻", size=80)],
        expanded=True,
        on_change=lambda e: print(f"Tile was {'expanded' if e.data else 'collapsed'}"),
    )

    def expand_tile(_: ft.Event[ft.FilledButton]):
        tile.expanded = True
        tile.update()

    def collapse_tile(_: ft.Event[ft.OutlinedButton]):
        tile.expanded = False
        tile.update()

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Row(
                        alignment=ft.MainAxisAlignment.CENTER,
                        controls=[
                            ft.FilledButton("Expand Tile", on_click=expand_tile),
                            ft.OutlinedButton("Collapse Tile", on_click=collapse_tile),
                        ],
                    ),
                    tile,
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Custom animations

import flet as ft


def main(page: ft.Page):
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER
    page.spacing = 20

    tile = ft.ExpansionTile(
        expanded=True,
        title=ft.Text("Expand/Collapse me while being attentive to the animations!"),
        controls=[
            ft.ListTile(title=ft.Text("Sub-item 1")),
            ft.ListTile(title=ft.Text("Sub-item 2")),
            ft.ListTile(title=ft.Text("Sub-item 3")),
        ],
    )

    def switch_animation(e: ft.Event[ft.CupertinoSlidingSegmentedButton]):
        if e.control.selected_index == 0:
            tile.animation_style = None
        elif e.control.selected_index == 1:
            tile.animation_style = ft.AnimationStyle(
                curve=ft.AnimationCurve.BOUNCE_OUT,
                duration=ft.Duration(seconds=5),
            )
        else:
            tile.animation_style = ft.AnimationStyle.no_animation()
        tile.update()

    page.add(
        ft.SafeArea(
            content=ft.Column(
                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                controls=[
                    ft.CupertinoSlidingSegmentedButton(
                        selected_index=0,
                        thumb_color=ft.Colors.BLUE_400,
                        on_change=switch_animation,
                        controls=[
                            ft.Text("Default animation"),
                            ft.Text("Custom animation"),
                            ft.Text("No animation"),
                        ],
                    ),
                    tile,
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Theme mode toggle

import flet as ft


def main(page: ft.Page):
    page.spacing = 0
    page.padding = 0

    def handle_switch_change(_: ft.Event[ft.Switch]):
        if page.theme_mode == ft.ThemeMode.DARK:
            page.theme_mode = ft.ThemeMode.LIGHT
            switch.thumb_icon = ft.Icons.LIGHT_MODE
        else:
            switch.thumb_icon = ft.Icons.DARK_MODE
            page.theme_mode = ft.ThemeMode.DARK
        switch.update()

    def handle_expansion_tile_change(e: ft.Event[ft.ExpansionTile]):
        page.show_dialog(
            ft.SnackBar(
                duration=1000,
                content=ft.Text(
                    value=(
                        f"ExpansionTile was "
                        f"{'expanded' if e.data == 'true' else 'collapsed'}"
                    )
                ),
            )
        )
        if e.control.trailing:
            e.control.trailing.icon = (
                ft.Icons.ARROW_DROP_DOWN
                if e.control.trailing.icon == ft.Icons.ARROW_DROP_DOWN_CIRCLE
                else ft.Icons.ARROW_DROP_DOWN_CIRCLE
            )
            e.control.trailing.update()

    switch = ft.Switch(thumb_icon=ft.Icons.DARK_MODE, on_change=handle_switch_change)

    page.add(
        ft.SafeArea(
            content=ft.Column(
                spacing=0,
                controls=[
                    ft.ExpansionTile(
                        title=ft.Text("ExpansionTile 1"),
                        subtitle=ft.Text("Trailing expansion arrow icon"),
                        bgcolor=ft.Colors.BLUE_GREY_200,
                        collapsed_bgcolor=ft.Colors.BLUE_GREY_200,
                        affinity=ft.TileAffinity.PLATFORM,
                        maintain_state=True,
                        collapsed_text_color=ft.Colors.RED,
                        text_color=ft.Colors.RED,
                        controls=[
                            ft.ListTile(
                                title=ft.Text("This is sub-tile number 1"),
                                bgcolor=ft.Colors.BLUE_GREY_200,
                            )
                        ],
                    ),
                    ft.ExpansionTile(
                        title=ft.Text("ExpansionTile 2"),
                        subtitle=ft.Text("Custom expansion arrow icon"),
                        trailing=ft.Icon(ft.Icons.ARROW_DROP_DOWN),
                        collapsed_text_color=ft.Colors.GREEN,
                        text_color=ft.Colors.GREEN,
                        on_change=handle_expansion_tile_change,
                        controls=[
                            ft.ListTile(title=ft.Text("This is sub-tile number 2"))
                        ],
                    ),
                    ft.ExpansionTile(
                        title=ft.Text("ExpansionTile 3"),
                        subtitle=ft.Text("Leading expansion arrow icon"),
                        affinity=ft.TileAffinity.LEADING,
                        expanded=True,
                        collapsed_text_color=ft.Colors.BLUE_800,
                        text_color=ft.Colors.BLUE_200,
                        controls=[
                            ft.ListTile(title=ft.Text("This is sub-tile number 3")),
                            ft.ListTile(title=ft.Text("This is sub-tile number 4")),
                            ft.ListTile(title=ft.Text("This is sub-tile number 5")),
                        ],
                    ),
                    ft.Row(
                        expand=True,
                        alignment=ft.MainAxisAlignment.END,
                        controls=[
                            ft.Container(
                                padding=ft.Padding.only(bottom=50),
                                alignment=ft.Alignment.BOTTOM_RIGHT,
                                expand=True,
                                content=switch,
                            ),
                        ],
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Borders

import flet as ft


def main(page: ft.Page):
    page.theme_mode = ft.ThemeMode.LIGHT

    page.add(
        ft.SafeArea(
            content=ft.ExpansionTile(
                title=ft.Text(
                    value="Expansion Tile with changing borders",
                    text_align=ft.TextAlign.CENTER,
                ),
                subtitle=ft.Text(
                    value="Tile border changes when expanded",
                    text_align=ft.TextAlign.CENTER,
                ),
                bgcolor=ft.Colors.BLUE_GREY_200,
                controls_padding=ft.Padding.symmetric(horizontal=10),
                collapsed_bgcolor=ft.Colors.BLUE_GREY_200,
                affinity=ft.TileAffinity.PLATFORM,
                maintain_state=True,
                shape=ft.RoundedRectangleBorder(radius=20),
                collapsed_shape=ft.StadiumBorder(side=ft.BorderSide(width=2)),
                collapsed_text_color=ft.Colors.GREY_800,
                text_color=ft.Colors.GREY_800,
                controls=[
                    ft.ListTile(
                        title=ft.Text("A sub-tile"),
                        bgcolor=ft.Colors.BLUE_GREY_200,
                        shape=ft.RoundedRectangleBorder(radius=20),
                    ),
                    ft.ListTile(
                        title=ft.Text("Another sub-tile"),
                        bgcolor=ft.Colors.BLUE_GREY_200,
                        shape=ft.RoundedRectangleBorder(radius=20),
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Properties

affinityclass-attributeinstance-attribute

affinity: Optional[TileAffinity] = None

Typically used to force the expansion arrow icon to the tile's leading or trailing edge.

If None, flet.ListTileTheme.affinity is used; if that is also None, then defaults to flet.TileAffinity.TRAILING (the expansion arrow icon appears on the tile's trailing edge).

animation_styleclass-attributeinstance-attribute

animation_style: Optional[AnimationStyle] = None

Defines the animation style (curve and duration) for this tile's expansion and collapse.

If flet.AnimationStyle.duration is provided, it will be used to override the expansion animation duration. If it is None, then flet.AnimationStyle.duration from the flet.ExpansionTileTheme.animation_style will be used. If that is also None, Duration(milliseconds=200) will be used as default.

If flet.AnimationStyle.curve is provided, it will be used to override the expansion animation curve. If it is None, then flet.AnimationStyle.curve from the flet.ExpansionTileTheme.animation_style will be used. If that is also None, flet.AnimationCurve.EASE_IN will be used as default.

If flet.AnimationStyle.reverse_curve is provided, it will be used to override the collapse animation curve. If it is None, then flet.AnimationStyle.reverse_curve from the flet.ExpansionTileTheme.animation_style will be used. If that is also None, the expansion curve will be used as default.

Tip

To disable the animations, use flet.AnimationStyle.no_animation.

bgcolorclass-attributeinstance-attribute

bgcolor: Optional[ColorValue] = None

The color to display behind the sublist when expanded.

If None, flet.ExpansionTileTheme.bgcolor is used; if that is also None, then defaults to flet.Colors.TRANSPARENT.

clip_behaviorclass-attributeinstance-attribute

clip_behavior: Optional[ClipBehavior] = None

Defines how the content of this tile is clipped.

If set and a custom collapsed or expanded shape is provided, this value determines how this tile is clipped.

If None, flet.ExpansionTileTheme.clip_behavior is used; if that is also None, then defaults to flet.ClipBehavior.ANTI_ALIAS.

collapsed_bgcolorclass-attributeinstance-attribute

collapsed_bgcolor: Optional[ColorValue] = None

Defines the background color of this tile when the sublist is collapsed (expanded is False).

If None, flet.ExpansionTileTheme.collapsed_bgcolor is used; if that is also None, then defaults to flet.Colors.TRANSPARENT.

collapsed_icon_colorclass-attributeinstance-attribute

collapsed_icon_color: Optional[ColorValue] = None

The icon color of this tile's expansion arrow icon when the sublist is collapsed (expanded is False).

If None, flet.ExpansionTileTheme.collapsed_icon_color is used; if that is also None, then defaults to flet.ColorScheme.on_surface of the flet.Page.theme.

collapsed_shapeclass-attributeinstance-attribute

collapsed_shape: Optional[OutlinedBorder] = None

The tile's border shape when the sublist is collapsed.

If None, flet.ExpansionTileTheme.shape is used; if that is also None, then defaults to a Border with vertical sides of color flet.Colors.TRANSPARENT.

collapsed_text_colorclass-attributeinstance-attribute

collapsed_text_color: Optional[ColorValue] = None

The color of this tile's titles when the sublist is collapsed (expanded is False).

If None, flet.ExpansionTileTheme.collapsed_text_color is used; if that is also None, then defaults to body_large of the flet.Theme.text_theme.

controlsclass-attributeinstance-attribute

controls: Optional[list[Control]] = None

The controls to be displayed when this tile expanded.

Typically a list of ListTile controls.

controls_paddingclass-attributeinstance-attribute

controls_padding: Optional[PaddingValue] = None

Defines the padding around the controls.

If None, flet.ExpansionTileTheme.controls_padding is used; if that is also None, then defaults to Padding.all(0).

denseclass-attributeinstance-attribute

dense: Optional[bool] = None

Whether this list tile is part of a vertically dense list.

Dense tiles default to having a smaller height.

It is not recommended to set this property to True when in Material3.

If None, then its value is based on flet.ListTileTheme.dense.

enable_feedbackclass-attributeinstance-attribute

enable_feedback: bool = True

Whether detected gestures should provide acoustic and/or haptic feedback. For example, on Android a tap will produce a clicking sound and a long-press will produce a short vibration, when feedback is enabled.

expandedclass-attributeinstance-attribute

expanded: bool = False

The expansion state of this tile.

True - expanded, False - collapsed.

expanded_alignmentclass-attributeinstance-attribute

expanded_alignment: Optional[Alignment] = None

Defines the alignment of controls, which are arranged in a column when the tile is expanded.

If None, flet.ExpansionTileTheme.expanded_alignment is used; if that is also None, then defaults to flet.Alignment.CENTER.

expanded_cross_axis_alignmentclass-attributeinstance-attribute

expanded_cross_axis_alignment: CrossAxisAlignment = CrossAxisAlignment.CENTER

Defines the alignment of each child control within controls when the tile is expanded.

Raises:

ValueError - If set to flet.CrossAxisAlignment.BASELINE.

icon_colorclass-attributeinstance-attribute

icon_color: Optional[ColorValue] = None

The icon color of this tile's expansion arrow icon when the sublist is expanded.

If None, flet.ExpansionTileTheme.icon_color is used; if that is also None, then defaults to flet.ColorScheme.primary of the flet.Page.theme.

leadingclass-attributeinstance-attribute

leading: Optional[IconDataOrControl] = None

A Control to display before the title.

Typically a CircleAvatar control.

Depending on the value of affinity, this control may replace the rotating expansion arrow icon.

maintain_stateclass-attributeinstance-attribute

maintain_state: bool = False

A boolean value which defines whether the state of the controls is maintained when this tile expanded and collapses.

When True, the children are kept in the tree while the tile is collapsed. When False (default), the controls are removed from the tree when the tile is collapsed and recreated upon expansion.

min_tile_heightclass-attributeinstance-attribute

min_tile_height: Optional[Number] = None

The minimum height of this tile.

If None, the default tile heights are 56.0, 72.0, and 88.0 for one, two, and three lines of text respectively. If dense is True, these defaults are changed to 48.0, 64.0, and 76.0. A visual density value or a large title will also adjust the default tile heights.

shapeclass-attributeinstance-attribute

shape: Optional[OutlinedBorder] = None

The border shape of this tile when the sublist is expanded.

If None, flet.ExpansionTileTheme.shape is used; if that is also None, then defaults to a Border with vertical sides of color flet.Theme.divider_color.

show_trailing_iconclass-attributeinstance-attribute

show_trailing_icon: bool = True

Whether this tile should build/show a default trailing icon, if trailing is None.

subtitleclass-attributeinstance-attribute

subtitle: Optional[StrOrControl] = None

Additional content displayed below the title.

Typically a Text control.

text_colorclass-attributeinstance-attribute

text_color: Optional[ColorValue] = None

The color of this tile's titles when the sublist is expanded.

If None, flet.ExpansionTileTheme.text_color is used; if that is also None, then defaults to body_large of the flet.Theme.text_theme.

tile_paddingclass-attributeinstance-attribute

tile_padding: Optional[PaddingValue] = None

Defines the tile's padding.

Analogous to flet.ListTile.content_padding, this property defines the insets for the leading, title, subtitle and trailing controls. It does not inset the expanded controls widgets.

If None, flet.ExpansionTileTheme.tile_padding is used; if that is also None, then defaults to Padding.symmetric(horizontal=16.0).

titleinstance-attribute

title: Annotated[StrOrControl, V.str_or_visible_control()]

A Control to display as primary content of this tile.

Typically a Text control.

Raises:

ValueError - If it is neither a string nor a visible Control.

trailingclass-attributeinstance-attribute

trailing: Optional[IconDataOrControl] = None

A Control to display after the title.

Typically an Icon control.

Depending on the value of affinity, this control may replace the rotating expansion arrow icon.

visual_densityclass-attributeinstance-attribute

visual_density: Optional[VisualDensity] = None

Defines how compact this tile's layout will be.

Events

on_changeclass-attributeinstance-attribute

on_change: Optional[ControlEventHandler[ExpansionTile]] = None

Called when a user clicks or taps the list tile.

The data property of the event handler argument is a boolean representing the expanded state of the tile after the change.

Properties

Events

Examples​

Basic Example​

Programmatic expansion/collapse​

Custom animations​

Theme mode toggle​

Borders​

Properties​

buildaffinityclass-attributeinstance-attribute​

buildanimation_styleclass-attributeinstance-attribute​

buildbgcolorclass-attributeinstance-attribute​

buildclip_behaviorclass-attributeinstance-attribute​

buildcollapsed_bgcolorclass-attributeinstance-attribute​

buildcollapsed_icon_colorclass-attributeinstance-attribute​

buildcollapsed_shapeclass-attributeinstance-attribute​

buildcollapsed_text_colorclass-attributeinstance-attribute​

buildcontrolsclass-attributeinstance-attribute​

buildcontrols_paddingclass-attributeinstance-attribute​

builddenseclass-attributeinstance-attribute​

buildenable_feedbackclass-attributeinstance-attribute​

buildexpandedclass-attributeinstance-attribute​

buildexpanded_alignmentclass-attributeinstance-attribute​

buildexpanded_cross_axis_alignmentclass-attributeinstance-attribute​

buildicon_colorclass-attributeinstance-attribute​

buildleadingclass-attributeinstance-attribute​

buildmaintain_stateclass-attributeinstance-attribute​

buildmin_tile_heightclass-attributeinstance-attribute​

buildshapeclass-attributeinstance-attribute​

buildshow_trailing_iconclass-attributeinstance-attribute​

buildsubtitleclass-attributeinstance-attribute​

buildtext_colorclass-attributeinstance-attribute​

buildtile_paddingclass-attributeinstance-attribute​

buildtitleinstance-attribute​

buildtrailingclass-attributeinstance-attribute​

buildvisual_densityclass-attributeinstance-attribute​

Events​

bolton_changeclass-attributeinstance-attribute​

Examples

Basic Example

Programmatic expansion/collapse

Custom animations

Theme mode toggle

Borders

Properties

affinityclass-attributeinstance-attribute

animation_styleclass-attributeinstance-attribute

bgcolorclass-attributeinstance-attribute

clip_behaviorclass-attributeinstance-attribute

collapsed_bgcolorclass-attributeinstance-attribute

collapsed_icon_colorclass-attributeinstance-attribute

collapsed_shapeclass-attributeinstance-attribute

collapsed_text_colorclass-attributeinstance-attribute

controlsclass-attributeinstance-attribute

controls_paddingclass-attributeinstance-attribute

denseclass-attributeinstance-attribute

enable_feedbackclass-attributeinstance-attribute

expandedclass-attributeinstance-attribute

expanded_alignmentclass-attributeinstance-attribute

expanded_cross_axis_alignmentclass-attributeinstance-attribute

icon_colorclass-attributeinstance-attribute

leadingclass-attributeinstance-attribute

maintain_stateclass-attributeinstance-attribute

min_tile_heightclass-attributeinstance-attribute

shapeclass-attributeinstance-attribute

show_trailing_iconclass-attributeinstance-attribute

subtitleclass-attributeinstance-attribute

text_colorclass-attributeinstance-attribute

tile_paddingclass-attributeinstance-attribute

titleinstance-attribute

trailingclass-attributeinstance-attribute

visual_densityclass-attributeinstance-attribute

Events

on_changeclass-attributeinstance-attribute