Skip to content

SearchBar

Manages a "search view" route that allows the user to select one of the suggested completions for a search query.

Inherits: LayoutControl

Properties

Events

Methods

Examples#

Live example

Basic Example#

import flet as ft


def main(page: ft.Page):
    async def handle_tile_click(e: ft.Event[ft.ListTile]):
        await anchor.close_view(e.control.title.value)

    async def open_click():
        await anchor.open_view()

    def handle_change(e: ft.Event[ft.SearchBar]):
        print(f"handle_change e.data: {e.data}")

    def handle_submit(e: ft.Event[ft.SearchBar]):
        print(f"handle_submit e.data: {e.data}")

    async def handle_tap(e: ft.Event[ft.SearchBar]):
        print("handle_tap")
        await anchor.open_view()

    page.add(
        ft.Row(
            alignment=ft.MainAxisAlignment.CENTER,
            controls=[
                ft.OutlinedButton(
                    content="Open Search View",
                    on_click=open_click,
                ),
            ],
        ),
        anchor := ft.SearchBar(
            view_elevation=4,
            divider_color=ft.Colors.AMBER,
            bar_hint_text="Search colors...",
            view_hint_text="Choose a color from the suggestions...",
            on_change=handle_change,
            on_submit=handle_submit,
            on_tap=handle_tap,
            controls=[
                ft.ListTile(title=ft.Text(f"Color {i}"), on_click=handle_tile_click)
                for i in range(10)
            ],
        ),
    )


ft.run(main)

basic

Properties#

autofocus #

autofocus: bool = False

Whether the text field should focus itself if nothing else is already focused.

Defaults to False.

bar_bgcolor #

bar_bgcolor: ControlStateValue[ColorValue] | None = None

Defines the background color of the search bar in all or specific ControlState states.

bar_border_side #

bar_border_side: ControlStateValue[BorderSide] | None = None

The color and weight of the search bar's outline.

This value is combined with SearchBar.bar_shape to create a shape decorated with an outline.

bar_elevation #

bar_elevation: ControlStateValue[Number | None] | None = (
    None
)

The elevation of the search bar.

bar_hint_text #

bar_hint_text: str | None = None

Defines the text to be shown in the search bar when it is empty and the search view is close.

Usually some text that suggests what sort of input the field accepts.

bar_hint_text_style #

bar_hint_text_style: ControlStateValue[TextStyle] | None = (
    None
)

The style to use for the SearchBar.bar_hint_text.

bar_leading #

bar_leading: Control | None = None

A control to display before the text input field when the search view is close. This is typically an Icon or an IconButton.

bar_overlay_color #

bar_overlay_color: ControlStateValue[ColorValue] | None = (
    None
)

Defines the highlight color that's typically used to indicate that the search bar is in FOCUSED, HOVERED, or PRESSED states.

bar_padding #

bar_padding: ControlStateValue[PaddingValue] | None = None

The padding between the search bar's boundary and its contents.

bar_scroll_padding #

bar_scroll_padding: PaddingValue = 20

Configures the padding around a Scrollable when the text field scrolls into view.

If the bar's text field is partially off-screen or covered (e.g., by the keyboard), it scrolls into view, ensuring it is positioned at the specified distance from the Scrollable edges.

bar_shadow_color #

bar_shadow_color: ControlStateValue[ColorValue] | None = (
    None
)

The shadow color of the search bar.

bar_shape #

bar_shape: ControlStateValue[OutlinedBorder] | None = None

The shape of the search bar.

This shape is combined with SearchBar.bar_border_side to create a shape decorated with an outline.

bar_size_constraints #

bar_size_constraints: BoxConstraints | None = None

Optional size constraints for the search bar.

bar_text_style #

bar_text_style: ControlStateValue[TextStyle] | None = None

The style to use for the text being edited.

bar_trailing #

bar_trailing: list[Control] | None = None

A list of controls to display after the text input field when the search view is close.

These controls can represent additional modes of searching (e.g voice search), an avatar, or an overflow menu and are usually not more than two.

capitalization #

capitalization: TextCapitalization | None = None

Enables automatic on-the-fly capitalization of entered text.

controls #

controls: list[Control] = field(default_factory=list)

The list of controls to be displayed below the search bar when in search view. These controls are usually ListTiles and will be displayed in a ListView.

divider_color #

divider_color: ColorValue | None = None

The color of the divider when in search view.

full_screen #

full_screen: bool = False

Defines whether the search view grows to fill the entire screen when the search bar is tapped. Defaults to False.

keyboard_type #

keyboard_type: KeyboardType = TEXT

The type of action button to use for the keyboard.

shrink_wrap #

shrink_wrap: bool | None = None

Whether the search view should shrink-wrap its contents.

value #

value: str = ''

The text in the search bar.

view_bar_padding #

view_bar_padding: PaddingValue | None = None

The padding to use for the search view's search bar.

If null, then the default value is 8.0 horizontally.

view_bgcolor #

view_bgcolor: ColorValue | None = None

Defines the background color of the search view.

view_elevation #

view_elevation: Number | None = None

Defines the elevation of the search view.

view_header_height #

view_header_height: Number | None = None

The height of the search field on the search view.

view_header_text_style #

view_header_text_style: TextStyle | None = None

Defines the TextStyle of the text being edited on the search view.

view_hint_text #

view_hint_text: str | None = None

Defines the text to be displayed when the search bar's input field is empty.

view_hint_text_style #

view_hint_text_style: TextStyle | None = None

Defines the TextStyle of view_hint_text.

view_leading #

view_leading: Control | None = None

A Control to display before the text input field when the search view is open. Typically an Icon or an IconButton.

Defaults to a back button which closes/pops the search view.

view_padding #

view_padding: PaddingValue | None = None

The padding to use for the search view.

Has no effect if the search view is full-screen.

view_shape #

view_shape: OutlinedBorder | None = None

Defines the shape of the search view.

view_side #

view_side: BorderSide | None = None

Defines the color and weight of the search view's outline.

view_size_constraints #

view_size_constraints: BoxConstraints | None = None

Optional size constraints for the search view.

By default, the search view has the same width as the search bar and is ⅔ the height of the screen. If the width and height of the view are within the view_size_constraints, the view will show its default size. Otherwise, the size of the view will be constrained by this property.

view_trailing #

view_trailing: list[Control] | None = None

A list of Controls to display after the text input field when the search view is open.

Defaults to a close button which closes/pops the search view.

Events#

on_blur #

on_blur: ControlEventHandler[SearchBar] | None = None

TBD

on_change #

on_change: ControlEventHandler[SearchBar] | None = None

Called when the typed input in the search bar has changed.

on_focus #

on_focus: ControlEventHandler[SearchBar] | None = None

TBD

on_submit #

on_submit: ControlEventHandler[SearchBar] | None = None

Called when user presses ENTER while focus is on SearchBar.

on_tap #

on_tap: ControlEventHandler[SearchBar] | None = None

Called when the search bar is tapped.

on_tap_outside_bar #

on_tap_outside_bar: (
    ControlEventHandler[SearchBar] | None
) = None

TBD

Methods#

blur #

blur()

close_view #

close_view(text: str | None = None)

focus #

focus()

open_view #

open_view()