ExpandedDockedSearchBar

Component in Material 3 Compose

[ExpandedDockedSearchBar] represents a search bar that is currently expanding or in the expanded state, showing search results. This component is displayed in a popup over the collapsed search bar. It is recommended to use [ExpandedDockedSearchBar] on medium and large screens such as tablets, and to instead use [ExpandedFullScreenSearchBar] on compact screen such as phones.

Last updated: 2025-03-21 11:59

Installation

dependencies {
   implementation("androidx.compose.material3:material3:1.4.0-alpha10")
}

Overloads

@ExperimentalMaterial3Api
@Composable
fun ExpandedDockedSearchBar(
    state: SearchBarState,
    inputField: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    shape: Shape = SearchBarDefaults.dockedShape,
    colors: SearchBarColors = SearchBarDefaults.colors(),
    tonalElevation: Dp = SearchBarDefaults.TonalElevation,
    shadowElevation: Dp = SearchBarDefaults.ShadowElevation,
    properties: PopupProperties = PopupProperties(focusable = true, clippingEnabled = false),
    content: @Composable ColumnScope.() -> Unit,
)

Parameters

name	description
state	the state of the search bar. This state should also be passed to the [inputField] and the collapsed search bar.
inputField	the input field of this search bar that allows entering a query, typically a [SearchBarDefaults.InputField].
modifier	the [Modifier] to be applied to this expanded search bar.
shape	the shape of this search bar.
colors	[SearchBarColors] that will be used to resolve the colors used for this search bar in different states. See [SearchBarDefaults.colors].
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].
shadowElevation	the elevation for the shadow below this search bar.
properties	the platform-specific properties to configure the dialog's behavior. Any properties which limit the dialog's size (e.g. [DialogProperties.usePlatformDefaultWidth]) are ignored.
content	the content of this search bar to display search results below the [inputField].

Code Example

DockedSearchBarScaffoldSample

@Preview
@Composable
fun DockedSearchBarScaffoldSample() {
    val textFieldState = rememberTextFieldState()
    val searchBarState = rememberSearchBarState()
    val scope = rememberCoroutineScope()
    val scrollBehavior = SearchBarDefaults.enterAlwaysSearchBarScrollBehavior()

    val inputField =
        @Composable {
            SearchBarDefaults.InputField(
                modifier = Modifier,
                searchBarState = searchBarState,
                textFieldState = textFieldState,
                onSearch = { scope.launch { searchBarState.animateToCollapsed() } },
                placeholder = { Text("Search...") },
                leadingIcon = {
                    if (searchBarState.currentValue == SearchBarValue.Expanded) {
                        IconButton(
                            onClick = { scope.launch { searchBarState.animateToCollapsed() } }
                        ) {
                            Icon(Icons.AutoMirrored.Default.ArrowBack, contentDescription = "Back")
                        }
                    } else {
                        Icon(Icons.Default.Search, contentDescription = null)
                    }
                },
                trailingIcon = { Icon(Icons.Default.MoreVert, contentDescription = null) },
            )
        }

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopSearchBar(
                scrollBehavior = scrollBehavior,
                state = searchBarState,
                inputField = inputField,
            )
            ExpandedDockedSearchBar(
                state = searchBarState,
                inputField = inputField,
            ) {
                SearchResults(
                    onResultClick = { result ->
                        textFieldState.setTextAndPlaceCursorAtEnd(result)
                        scope.launch { searchBarState.animateToCollapsed() }
                    }
                )
            }
        }
    ) { padding ->
        LazyColumn(
            contentPadding = padding,
            verticalArrangement = Arrangement.spacedBy(8.dp),
        ) {
            val list = List(100) { "Text $it" }
            items(count = list.size) {
                Text(
                    text = list[it],
                    modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp),
                )
            }
        }
    }
}