Docked and full-screen search

Two ways to show search results: in a dropdown under the field or on a full-screen surface.

Category: Navigation
API status: Expressive
Compose APIs: DockedSearchBar, SearchBar, ExpandedFullScreenSearchBar, SearchBarDefaults.InputField
Interactive page: https://m3e.ljzapps.app/#components/full-screen-search

When to use

Use the docked search bar on large windows, where a dropdown under the field is easy to reach. Use the full-screen expanded search on compact windows, where it gives the results the whole screen.

Both share the same input field. Choose by window size class.

Examples

Docked

Results appear below the field.

var query by rememberSaveable { mutableStateOf("") }
var expanded by rememberSaveable { mutableStateOf(false) }
val cities = listOf("Berlin", "Bergen", "Barcelona", "Boston", "Brussels")

Box(Modifier.fillMaxWidth().height(320.dp), contentAlignment = Alignment.TopCenter) {
    DockedSearchBar(
        inputField = {
            SearchBarDefaults.InputField(
                query = query,
                onQueryChange = { query = it },
                onSearch = { expanded = false },
                expanded = expanded,
                onExpandedChange = { expanded = it },
                placeholder = { Text("Search cities") },
                leadingIcon = { Icon(Icons.Rounded.Search, contentDescription = null) },
            )
        },
        expanded = expanded,
        onExpandedChange = { expanded = it },
    ) {
        cities.filter { it.contains(query, ignoreCase = true) }.forEach { city ->
            ListItem(headlineContent = { Text(city) })
        }
    }
}

Full screen

The expanded bar covers the window.

val searchBarState = rememberSearchBarState()
val textFieldState = rememberTextFieldState()
val scope = rememberCoroutineScope()
val inputField = @Composable {
    SearchBarDefaults.InputField(
        textFieldState = textFieldState,
        searchBarState = searchBarState,
        onSearch = { scope.launch { searchBarState.animateToCollapsed() } },
        placeholder = { Text("Search the library") },
        leadingIcon = { Icon(Icons.Rounded.Search, contentDescription = null) },
    )
}

Box(Modifier.fillMaxWidth().height(120.dp), contentAlignment = Alignment.TopCenter) {
    SearchBar(state = searchBarState, inputField = inputField)
    ExpandedFullScreenSearchBar(state = searchBarState, inputField = inputField) {
        listOf("Albums", "Artists", "Playlists").forEach { label ->
            ListItem(headlineContent = { Text(label) })
        }
    }
}

Parameters

Name	Type	Description
`state`	`SearchBarState`	Full screen variant. Animates between Collapsed and Expanded.
`expanded / onExpandedChange`	`Boolean / (Boolean) -> Unit`	Docked variant state.
`inputField`	`@Composable () -> Unit`	SearchBarDefaults.InputField.
`content`	`@Composable ColumnScope.() -> Unit`	Suggestions or results.

Guidelines

Do:

Show recent searches.
Keep the field visible while results are shown.

Don't:

Do not use the docked variant on compact windows.
Do not search on every keystroke without a delay.

Accessibility

Escape collapses the expanded bar. Announce the number of results.