IconButton

An icon button is a round button with an icon in the middle that reacts to touches by filling with color (ink).

Icon buttons are commonly used in the toolbars, but they can be used in many other places as well.

ft.IconButton(icon=ft.Icons.FAVORITE, icon_color=ft.Colors.PRIMARY)

Basic IconButton

Inherits: LayoutControl, AdaptiveControl

Properties

• alignment - Defines how the icon is positioned within this button.
• autofocus - Whether this control will be provided initial focus.
• bgcolor - The background color of this button.
• disabled_color - The color to use for the icon inside the button when disabled.
• enable_feedback - Whether detected gestures should provide acoustic and/or haptic feedback.
• focus_color - The color of this button when in focus.
• highlight_color - The color of this button when it is pressed.
• hover_color - The color of this button when hovered.
• icon - An icon to be shown in this button.
• icon_color - The foreground color of the icon.
• icon_size - The icon's size in virtual pixels.
• mouse_cursor - The cursor to be displayed when a mouse pointer enters or is hovering over this control.
• padding - Defines the padding around this button.
• selected - The optional selection state of this button.
• selected_icon - The icon to be shown in this button for the 'selected' state.
• selected_icon_color - The icon color for the 'selected' state of this button.
• size_constraints - Size constraints for this button.
• splash_color - The primary color of this button when it is in the pressed state.
• splash_radius - The splash radius.
• style - Customizes this button's appearance.
• url - The URL to open when this button is clicked.
• visual_density - Defines how compact this button's layout will be.

Events

• on_blur - Called when this button has lost focus.
• on_click - Called when a user clicks this button.
• on_focus - Called when this button has received focus.
• on_hover - Called when the button is hovered.
• on_long_press - Called when the button is long-pressed.

Methods

• focus - Moves focus to this button.

Examples

Live example

Handling clicks

import flet as ft


def main(page: ft.Page):
    page.title = "IconButton Example"

    def button_clicked(e: ft.Event[ft.IconButton]):
        button.data += 1
        message.value = f"Button clicked {button.data} time(s)"
        message.update()

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    button := ft.IconButton(
                        icon=ft.Icons.PLAY_CIRCLE_FILL_OUTLINED,
                        data=0,
                        on_click=button_clicked,
                    ),
                    message := ft.Text(),
                ],
            ),
        )
    )


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

Selected icon

import flet as ft


def main(page: ft.Page):
    page.title = "IconButton Example"
    page.padding = 10
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER
    page.vertical_alignment = ft.MainAxisAlignment.CENTER

    def handle_click(e: ft.Event[ft.IconButton]):
        e.control.selected = not e.control.selected
        e.control.update()

    page.add(
        ft.SafeArea(
            content=ft.IconButton(
                icon=ft.Icons.BATTERY_1_BAR,
                selected_icon=ft.Icons.BATTERY_FULL,
                scale=5,
                on_click=handle_click,
                selected=False,
                style=ft.ButtonStyle(
                    color={
                        ft.ControlState.SELECTED: ft.Colors.GREEN,
                        ft.ControlState.DEFAULT: ft.Colors.RED,
                    }
                ),
            ),
        )
    )


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

Properties

buildalignmentclass-attributeinstance-attribute

alignment: Optional[Alignment] = None

Defines how the icon is positioned within this button.

Defaults to flet.Alignment.CENTER.

buildautofocusclass-attributeinstance-attribute

autofocus: bool = False

Whether this control will be provided initial focus. If there is more than one control on a page with autofocus set, then the first one added to the page will get focus.

buildbgcolorclass-attributeinstance-attribute

bgcolor: Optional[ColorValue] = field(default=None, metadata={'skip': True})

The background color of this button.

builddisabled_colorclass-attributeinstance-attribute

disabled_color: Optional[ColorValue] = None

The color to use for the icon inside the button when disabled.

buildenable_feedbackclass-attributeinstance-attribute

enable_feedback: Optional[bool] = None

Whether detected gestures should provide acoustic and/or haptic feedback. On Android, for example, setting this to True produce a click sound and a long-press will produce a short vibration.

buildfocus_colorclass-attributeinstance-attribute

focus_color: Optional[ColorValue] = None

The color of this button when in focus.

buildhighlight_colorclass-attributeinstance-attribute

highlight_color: Optional[ColorValue] = None

The color of this button when it is pressed. The highlight fades in quickly as this button is pressed/held down.

buildhover_colorclass-attributeinstance-attribute

hover_color: Optional[ColorValue] = None

The color of this button when hovered.

buildiconclass-attributeinstance-attribute

icon: Optional[IconDataOrControl] = None

An icon to be shown in this button.

buildicon_colorclass-attributeinstance-attribute

icon_color: Optional[ColorValue] = None

The foreground color of the icon.

buildicon_sizeclass-attributeinstance-attribute

icon_size: Optional[Number] = None

The icon's size in virtual pixels.

Defaults to 24.

buildmouse_cursorclass-attributeinstance-attribute

mouse_cursor: Optional[MouseCursor] = field(default=None, metadata={'skip': True})

The cursor to be displayed when a mouse pointer enters or is hovering over this control.

buildpaddingclass-attributeinstance-attribute

padding: Optional[PaddingValue] = None

Defines the padding around this button. The entire padded icon will react to input gestures.

Defaults to Padding.all(8).

buildselectedclass-attributeinstance-attribute

selected: Optional[bool] = None

The optional selection state of this button.

If this property is not set, the button will behave as a normal push button, otherwise, the button will toggle between showing icon (when False), and selected_icon (when True).

buildselected_iconclass-attributeinstance-attribute

selected_icon: Optional[IconDataOrControl] = None

The icon to be shown in this button for the 'selected' state.

buildselected_icon_colorclass-attributeinstance-attribute

selected_icon_color: Optional[ColorValue] = None

The icon color for the 'selected' state of this button.

buildsize_constraintsclass-attributeinstance-attribute

size_constraints: Optional[BoxConstraints] = None

Size constraints for this button.

buildsplash_colorclass-attributeinstance-attribute

splash_color: Optional[ColorValue] = None

The primary color of this button when it is in the pressed state.

buildsplash_radiusclass-attributeinstance-attribute

splash_radius: Annotated[Optional[Number], V.gt(0)] = None

The splash radius.

Note

This value is honoured only when in Material 2 (flet.Theme.use_material3 is False).

Raises:

• ValueError - If it is not strictly greater than 0.

buildstyleclass-attributeinstance-attribute

style: Optional[ButtonStyle] = None

Customizes this button's appearance.

Note

• Only honoured in Material 3 design (flet.Theme.use_material3 is True).
• If flet.Theme.use_material3 is True, any parameters defined in style will be overridden by the corresponding parameters in this button. For example, if icon button visual_density is set to flet.VisualDensity.STANDARD and style's visual_density is set to flet.VisualDensity.COMPACT, flet.VisualDensity.STANDARD will be used.

buildurlclass-attributeinstance-attribute

url: Optional[Union[str, Url]] = None

The URL to open when this button is clicked.

Additionally, if on_click event callback is provided, it is fired after that.

buildvisual_densityclass-attributeinstance-attribute

visual_density: Optional[VisualDensity] = field(default=None, metadata={'skip': True})

Defines how compact this button's layout will be.

Events

bolton_blurclass-attributeinstance-attribute

on_blur: Optional[ControlEventHandler[IconButton]] = None

Called when this button has lost focus.

bolton_clickclass-attributeinstance-attribute

on_click: Optional[ControlEventHandler[IconButton]] = None

Called when a user clicks this button.

bolton_focusclass-attributeinstance-attribute

on_focus: Optional[ControlEventHandler[IconButton]] = None

Called when this button has received focus.

bolton_hoverclass-attributeinstance-attribute

on_hover: Optional[ControlEventHandler[IconButton]] = None

Called when the button is hovered.

bolton_long_pressclass-attributeinstance-attribute

on_long_press: Optional[ControlEventHandler[IconButton]] = None

Called when the button is long-pressed.

Methods

deployed_codefocusasync

focus()

Moves focus to this button.