{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

SearchBarKt

public final class SearchBarKt


Summary

Public methods

static final void
@ExperimentalMaterial3Api
@Composable
DockedSearchBar(
    @NonNull String query,
    @NonNull Function1<@NonNull StringUnit> onQueryChange,
    @NonNull Function1<@NonNull StringUnit> onSearch,
    boolean active,
    @NonNull Function1<@NonNull BooleanUnit> onActiveChange,
    @NonNull Modifier modifier,
    boolean enabled,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @NonNull Shape shape,
    @NonNull SearchBarColors colors,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> content
)

Material Design search.

static final void
@ExperimentalMaterial3Api
@Composable
SearchBar(
    @NonNull String query,
    @NonNull Function1<@NonNull StringUnit> onQueryChange,
    @NonNull Function1<@NonNull StringUnit> onSearch,
    boolean active,
    @NonNull Function1<@NonNull BooleanUnit> onActiveChange,
    @NonNull Modifier modifier,
    boolean enabled,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @NonNull Shape shape,
    @NonNull SearchBarColors colors,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @NonNull WindowInsets windowInsets,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> content
)

Material Design search.

Public methods

DockedSearchBar

@ExperimentalMaterial3Api
@Composable
public static final void DockedSearchBar(
    @NonNull String query,
    @NonNull Function1<@NonNull StringUnit> onQueryChange,
    @NonNull Function1<@NonNull StringUnit> onSearch,
    boolean active,
    @NonNull Function1<@NonNull BooleanUnit> onActiveChange,
    @NonNull Modifier modifier,
    boolean enabled,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @NonNull Shape shape,
    @NonNull SearchBarColors colors,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> content
)

Material Design search.

A search bar represents a floating search field that allows users to enter a keyword or phrase and get relevant information. It can be used as a way to navigate through an app via search queries.

An active search bar expands into a search "view" and can be used to display dynamic suggestions.

Search bar image

A DockedSearchBar displays search results in a bounded table below the input field. It is meant to be an alternative to SearchBar when expanding to full-screen size is undesirable on large screens such as tablets.

An example looks like:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MoreVert
import androidx.compose.material.icons.filled.Search
import androidx.compose.material.icons.filled.Star
import androidx.compose.material3.DockedSearchBar
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.SearchBar
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.isTraversalGroup
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.semantics.traversalIndex
import androidx.compose.ui.unit.dp

var text by rememberSaveable { mutableStateOf("") }
var active by rememberSaveable { mutableStateOf(false) }

Box(Modifier.fillMaxSize().semantics { isTraversalGroup = true }) {
    DockedSearchBar(
        modifier = Modifier
            .align(Alignment.TopCenter)
            .padding(top = 8.dp)
            .semantics { traversalIndex = -1f },
        query = text,
        onQueryChange = { text = it },
        onSearch = { active = false },
        active = active,
        onActiveChange = { active = it },
        placeholder = { Text("Hinted search text") },
        leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
        trailingIcon = { Icon(Icons.Default.MoreVert, contentDescription = null) },
    ) {
        repeat(4) { idx ->
            val resultText = "Suggestion $idx"
            ListItem(
                headlineContent = { Text(resultText) },
                supportingContent = { Text("Additional info") },
                leadingContent = { Icon(Icons.Filled.Star, contentDescription = null) },
                modifier = Modifier
                    .clickable {
                        text = resultText
                        active = false
                    }
                    .fillMaxWidth()
                    .padding(horizontal = 16.dp, vertical = 4.dp)
            )
        }
    }

    LazyColumn(
        contentPadding = PaddingValues(start = 16.dp, top = 72.dp, end = 16.dp, bottom = 16.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        val list = List(100) { "Text $it" }
        items(count = list.size) {
            Text(list[it], Modifier.fillMaxWidth().padding(horizontal = 16.dp))
        }
    }
}
Parameters
@NonNull String query

the query text to be shown in the search bar's input field

@NonNull Function1<@NonNull StringUnit> onQueryChange

the callback to be invoked when the input service updates the query. An updated text comes as a parameter of the callback.

@NonNull Function1<@NonNull StringUnit> onSearch

the callback to be invoked when the input service triggers the ImeAction.Search action. The current query comes as a parameter of the callback.

boolean active

whether this search bar is active

@NonNull Function1<@NonNull BooleanUnit> onActiveChange

the callback to be invoked when this search bar's active state is changed

@NonNull Modifier modifier

the Modifier to be applied to this search bar

boolean enabled

controls the enabled state of this search bar. When false, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.

@Composable Function0<Unit> placeholder

the placeholder to be displayed when the search bar's query is empty.

@Composable Function0<Unit> leadingIcon

the leading icon to be displayed at the beginning of the search bar container

@Composable Function0<Unit> trailingIcon

the trailing icon to be displayed at the end of the search bar container

@NonNull Shape shape

the shape of this search bar

@NonNull SearchBarColors colors

SearchBarColors that will be used to resolve the colors used for this search bar in different states. See SearchBarDefaults.colors.

@NonNull Dp tonalElevation

when SearchBarColors.containerColor is ColorScheme.surface, a translucent primary color overlay is applied on top of the container. A higher tonal elevation value will result in a darker color in light theme and lighter color in dark theme. See also: Surface.

@NonNull Dp shadowElevation

the elevation for the shadow below the search bar

@NonNull MutableInteractionSource interactionSource

the MutableInteractionSource representing the stream of Interactions for this search bar. You can create and pass in your own remembered instance to observe Interactions and customize the appearance / behavior of this search bar in different states.

@Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> content

the content of this search bar that will be displayed below the input field

SearchBar

@ExperimentalMaterial3Api
@Composable
public static final void SearchBar(
    @NonNull String query,
    @NonNull Function1<@NonNull StringUnit> onQueryChange,
    @NonNull Function1<@NonNull StringUnit> onSearch,
    boolean active,
    @NonNull Function1<@NonNull BooleanUnit> onActiveChange,
    @NonNull Modifier modifier,
    boolean enabled,
    @Composable Function0<Unit> placeholder,
    @Composable Function0<Unit> leadingIcon,
    @Composable Function0<Unit> trailingIcon,
    @NonNull Shape shape,
    @NonNull SearchBarColors colors,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @NonNull WindowInsets windowInsets,
    @NonNull MutableInteractionSource interactionSource,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> content
)

Material Design search.

A search bar represents a floating search field that allows users to enter a keyword or phrase and get relevant information. It can be used as a way to navigate through an app via search queries.

An active search bar expands into a search "view" and can be used to display dynamic suggestions.

Search bar image

A SearchBar expands to occupy the entirety of its allowed size when active. For full-screen behavior as specified by Material guidelines, parent layouts of the SearchBar must not pass any Constraints that limit its size, and the host activity should set WindowCompat.setDecorFitsSystemWindows(window, false).

If this expansion behavior is undesirable, for example on large tablet screens, DockedSearchBar can be used instead.

An example looks like:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MoreVert
import androidx.compose.material.icons.filled.Search
import androidx.compose.material.icons.filled.Star
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.SearchBar
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.isTraversalGroup
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.semantics.traversalIndex
import androidx.compose.ui.unit.dp

var text by rememberSaveable { mutableStateOf("") }
var active by rememberSaveable { mutableStateOf(false) }

Box(Modifier.fillMaxSize().semantics { isTraversalGroup = true }) {
    SearchBar(
        modifier = Modifier
            .align(Alignment.TopCenter)
            .semantics { traversalIndex = -1f },
        query = text,
        onQueryChange = { text = it },
        onSearch = { active = false },
        active = active,
        onActiveChange = {
            active = it
        },
        placeholder = { Text("Hinted search text") },
        leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
        trailingIcon = { Icon(Icons.Default.MoreVert, contentDescription = null) },
    ) {
        repeat(4) { idx ->
            val resultText = "Suggestion $idx"
            ListItem(
                headlineContent = { Text(resultText) },
                supportingContent = { Text("Additional info") },
                leadingContent = { Icon(Icons.Filled.Star, contentDescription = null) },
                modifier = Modifier
                    .clickable {
                        text = resultText
                        active = false
                    }
                    .fillMaxWidth()
                    .padding(horizontal = 16.dp, vertical = 4.dp)
            )
        }
    }

    LazyColumn(
        contentPadding = PaddingValues(start = 16.dp, top = 72.dp, end = 16.dp, bottom = 16.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        val list = List(100) { "Text $it" }
        items(count = list.size) {
            Text(list[it], Modifier.fillMaxWidth().padding(horizontal = 16.dp))
        }
    }
}
Parameters
@NonNull String query

the query text to be shown in the search bar's input field

@NonNull Function1<@NonNull StringUnit> onQueryChange

the callback to be invoked when the input service updates the query. An updated text comes as a parameter of the callback.

@NonNull Function1<@NonNull StringUnit> onSearch

the callback to be invoked when the input service triggers the ImeAction.Search action. The current query comes as a parameter of the callback.

boolean active

whether this search bar is active

@NonNull Function1<@NonNull BooleanUnit> onActiveChange

the callback to be invoked when this search bar's active state is changed

@NonNull Modifier modifier

the Modifier to be applied to this search bar

boolean enabled

controls the enabled state of this search bar. When false, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.

@Composable Function0<Unit> placeholder

the placeholder to be displayed when the search bar's query is empty.

@Composable Function0<Unit> leadingIcon

the leading icon to be displayed at the beginning of the search bar container

@Composable Function0<Unit> trailingIcon

the trailing icon to be displayed at the end of the search bar container

@NonNull Shape shape

the shape of this search bar when it is not active. When active, the shape will always be SearchBarDefaults.fullScreenShape.

@NonNull SearchBarColors colors

SearchBarColors that will be used to resolve the colors used for this search bar in different states. See SearchBarDefaults.colors.

@NonNull Dp tonalElevation

when SearchBarColors.containerColor is ColorScheme.surface, a translucent primary color overlay is applied on top of the container. A higher tonal elevation value will result in a darker color in light theme and lighter color in dark theme. See also: Surface.

@NonNull Dp shadowElevation

the elevation for the shadow below the search bar

@NonNull WindowInsets windowInsets

the window insets that the search bar will respect

@NonNull MutableInteractionSource interactionSource

the MutableInteractionSource representing the stream of Interactions for this search bar. You can create and pass in your own remembered instance to observe Interactions and customize the appearance / behavior of this search bar in different states.

@Composable @ExtensionFunctionType @NonNull Function1<@NonNull ColumnScopeUnit> content

the content of this search bar that will be displayed below the input field