androidx.compose.material3.adaptive.navigationsuite

Interfaces

NavigationSuiteScaffoldState

A state object that can be hoisted to observe the navigation suite scaffold state.
Cmn
NavigationSuiteScope

The scope associated with the NavigationSuiteScope.
Cmn

Classes

NavigationSuiteColors

Represents the colors of a NavigationSuite.
Cmn
NavigationSuiteItemColors

Represents the colors of a NavigationSuiteScope.item.
Cmn
NavigationSuiteType

Class that describes the different navigation suite types of the NavigationSuiteScaffold.
Cmn

Objects

NavigationSuiteDefaults

Contains the default values used by the NavigationSuite.
Cmn
NavigationSuiteScaffoldDefaults

Contains the default values used by the NavigationSuiteScaffold.
Cmn

Annotations

ExperimentalMaterial3AdaptiveNavigationSuiteApi
Cmn

Enums

NavigationSuiteScaffoldValue

Possible values of NavigationSuiteScaffoldState.
Cmn

Top-level functions summary

Unit
@Composable
NavigationSuite(
    modifier: Modifier,
    layoutType: NavigationSuiteType,
    colors: NavigationSuiteColors,
    content: NavigationSuiteScope.() -> Unit
)

The default Material navigation component according to the current NavigationSuiteType to be used with the NavigationSuiteScaffold.
Cmn
Unit
@Composable
NavigationSuiteScaffold(
    navigationSuiteItems: NavigationSuiteScope.() -> Unit,
    modifier: Modifier,
    state: NavigationSuiteScaffoldState,
    layoutType: NavigationSuiteType,
    navigationSuiteColors: NavigationSuiteColors,
    containerColor: Color,
    contentColor: Color,
    content: @Composable () -> Unit
)

The Navigation Suite Scaffold wraps the provided content and places the adequate provided navigation component on the screen according to the current NavigationSuiteType.
Cmn
Unit
@Composable
NavigationSuiteScaffoldLayout(
    navigationSuite: @Composable () -> Unit,
    state: NavigationSuiteScaffoldState,
    layoutType: NavigationSuiteType,
    content: @Composable () -> Unit
)

Layout for a NavigationSuiteScaffold's content.
Cmn
NavigationSuiteScaffoldState

Create and remember a NavigationSuiteScaffoldState
Cmn

Top-level functions

Cmn 
@Composable
fun NavigationSuite(
    modifier: Modifier = Modifier,
    layoutType: NavigationSuiteType = NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(WindowAdaptiveInfoDefault),
    colors: NavigationSuiteColors = NavigationSuiteDefaults.colors(),
    content: NavigationSuiteScope.() -> Unit
): Unit

The default Material navigation component according to the current NavigationSuiteType to be used with the NavigationSuiteScaffold.

For specifics about each navigation component, see NavigationBar, NavigationRail, and PermanentDrawerSheet.

Parameters
modifier: Modifier = Modifier

the Modifier to be applied to the navigation component
layoutType: NavigationSuiteType = NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(WindowAdaptiveInfoDefault)

the current NavigationSuiteType of the NavigationSuiteScaffold. Defaults to NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo
colors: NavigationSuiteColors = NavigationSuiteDefaults.colors()

NavigationSuiteColors that will be used to determine the container (background) color of the navigation component and the preferred color for content inside the navigation component
content: NavigationSuiteScope.() -> Unit

the content inside the current navigation component, typically NavigationSuiteScope.items
Cmn 
@Composable
fun NavigationSuiteScaffold(
    navigationSuiteItems: NavigationSuiteScope.() -> Unit,
    modifier: Modifier = Modifier,
    state: NavigationSuiteScaffoldState = rememberNavigationSuiteScaffoldState(),
    layoutType: NavigationSuiteType = NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(WindowAdaptiveInfoDefault),
    navigationSuiteColors: NavigationSuiteColors = NavigationSuiteDefaults.colors(),
    containerColor: Color = NavigationSuiteScaffoldDefaults.containerColor,
    contentColor: Color = NavigationSuiteScaffoldDefaults.contentColor,
    content: @Composable () -> Unit = {}
): Unit

The Navigation Suite Scaffold wraps the provided content and places the adequate provided navigation component on the screen according to the current NavigationSuiteType.

The navigation component can be animated to be hidden or shown via a NavigationSuiteScaffoldState.

Example default usage:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.material3.adaptive.currentWindowAdaptiveInfo
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuite
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffold
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldDefaults
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldValue
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteType
import androidx.compose.material3.adaptive.navigationsuite.rememberNavigationSuiteScaffoldState
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp

var selectedItem by remember { mutableIntStateOf(0) }
val navItems = listOf("Songs", "Artists", "Playlists")
val navSuiteType =
    NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(currentWindowAdaptiveInfo())
val state = rememberNavigationSuiteScaffoldState()
val scope = rememberCoroutineScope()

NavigationSuiteScaffold(
    layoutType = navSuiteType,
    state = state,
    navigationSuiteItems = {
        navItems.forEachIndexed { index, navItem ->
            item(
                icon = { Icon(Icons.Filled.Favorite, contentDescription = navItem) },
                label = { Text(navItem) },
                selected = selectedItem == index,
                onClick = { selectedItem = index }
            )
        }
    }
) {
    // Screen content.
    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        val text =
            if (state.currentValue == NavigationSuiteScaffoldValue.Visible) {
                "displayed"
            } else {
                "hidden"
            }
        Text(
            modifier = Modifier.padding(16.dp),
            text = "Current NavigationSuiteType: $navSuiteType,\nit is $text",
            textAlign = TextAlign.Center
        )
        Button(onClick = { scope.launch { state.toggle() } }) {
            Text("Hide/show navigation component")
        }
    }
}

Example custom configuration usage:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.material3.adaptive.currentWindowAdaptiveInfo
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuite
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffold
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldDefaults
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldValue
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteType
import androidx.compose.material3.adaptive.navigationsuite.rememberNavigationSuiteScaffoldState
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp
import androidx.window.core.layout.WindowWidthSizeClass

var selectedItem by remember { mutableIntStateOf(0) }
val navItems = listOf("Songs", "Artists", "Playlists")
val adaptiveInfo = currentWindowAdaptiveInfo()
val state = rememberNavigationSuiteScaffoldState()
val scope = rememberCoroutineScope()
// Custom configuration that shows a navigation drawer in large screens.
val customNavSuiteType =
    with(adaptiveInfo) {
        if (windowSizeClass.windowWidthSizeClass == WindowWidthSizeClass.EXPANDED) {
            NavigationSuiteType.NavigationDrawer
        } else {
            NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(adaptiveInfo)
        }
    }

NavigationSuiteScaffold(
    layoutType = customNavSuiteType,
    state = state,
    navigationSuiteItems = {
        navItems.forEachIndexed { index, navItem ->
            item(
                icon = { Icon(Icons.Filled.Favorite, contentDescription = navItem) },
                label = { Text(navItem) },
                selected = selectedItem == index,
                onClick = { selectedItem = index }
            )
        }
    }
) {
    // Screen content.
    // Screen content.
    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        val text =
            if (state.currentValue == NavigationSuiteScaffoldValue.Visible) "displayed"
            else "hidden"
        Text(
            modifier = Modifier.padding(16.dp),
            text = "Current custom NavigationSuiteType: $customNavSuiteType, is $text",
            textAlign = TextAlign.Center
        )
        Button(onClick = { scope.launch { state.toggle() } }) {
            Text("Hide/show navigation component")
        }
    }
}
Parameters
navigationSuiteItems: NavigationSuiteScope.() -> Unit

the navigation items to be displayed
modifier: Modifier = Modifier

the Modifier to be applied to the navigation suite scaffold
state: NavigationSuiteScaffoldState = rememberNavigationSuiteScaffoldState()

the NavigationSuiteScaffoldState of this navigation suite scaffold
layoutType: NavigationSuiteType = NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(WindowAdaptiveInfoDefault)

the current NavigationSuiteType. Defaults to NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo
navigationSuiteColors: NavigationSuiteColors = NavigationSuiteDefaults.colors()

NavigationSuiteColors that will be used to determine the container (background) color of the navigation component and the preferred color for content inside the navigation component
containerColor: Color = NavigationSuiteScaffoldDefaults.containerColor

the color used for the background of the navigation suite scaffold, including the passed content composable. Use Color.Transparent to have no color
contentColor: Color = NavigationSuiteScaffoldDefaults.contentColor

the preferred color to be used for typography and iconography within the passed in content lambda inside the navigation suite scaffold.
content: @Composable () -> Unit = {}

the content of your screen
Cmn 
@Composable
fun NavigationSuiteScaffoldLayout(
    navigationSuite: @Composable () -> Unit,
    state: NavigationSuiteScaffoldState = rememberNavigationSuiteScaffoldState(),
    layoutType: NavigationSuiteType = NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(WindowAdaptiveInfoDefault),
    content: @Composable () -> Unit = {}
): Unit

Layout for a NavigationSuiteScaffold's content. This function wraps the content and places the navigationSuite component according to the given layoutType.

The usage of this function is recommended when you need some customization that is not viable via the use of NavigationSuiteScaffold. Example usage:

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationRail
import androidx.compose.material3.NavigationRailItem
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.adaptive.currentWindowAdaptiveInfo
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuite
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffold
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldDefaults
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldLayout
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteScaffoldValue
import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteType
import androidx.compose.material3.adaptive.navigationsuite.rememberNavigationSuiteScaffoldState
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.unit.dp

var selectedItem by remember { mutableIntStateOf(0) }
val navItems = listOf("Songs", "Artists", "Playlists")
val navSuiteType =
    NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(currentWindowAdaptiveInfo())
val state = rememberNavigationSuiteScaffoldState()
val scope = rememberCoroutineScope()

Surface {
    NavigationSuiteScaffoldLayout(
        state = state,
        navigationSuite = {
            // Custom Navigation Rail with centered items.
            if (navSuiteType == NavigationSuiteType.NavigationRail) {
                NavigationRail {
                    // Adding Spacers before and after the item so they are pushed towards the
                    // center of the NavigationRail.
                    Spacer(Modifier.weight(1f))
                    navItems.forEachIndexed { index, item ->
                        NavigationRailItem(
                            icon = { Icon(Icons.Filled.Favorite, contentDescription = item) },
                            label = { Text(item) },
                            selected = selectedItem == index,
                            onClick = { selectedItem = index }
                        )
                    }
                    Spacer(Modifier.weight(1f))
                }
            } else {
                NavigationSuite {
                    navItems.forEachIndexed { index, item ->
                        item(
                            icon = { Icon(Icons.Filled.Favorite, contentDescription = item) },
                            label = { Text(item) },
                            selected = selectedItem == index,
                            onClick = { selectedItem = index }
                        )
                    }
                }
            }
        }
    ) {
        // Screen content.
        Column(
            modifier = Modifier.fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            val text =
                if (state.currentValue == NavigationSuiteScaffoldValue.Visible) "displayed"
                else "hidden"
            Text(
                modifier = Modifier.padding(16.dp),
                text = "Current NavigationSuiteType: $navSuiteType, is $text",
                textAlign = TextAlign.Center
            )
            Button(onClick = { scope.launch { state.toggle() } }) {
                Text("Hide/show navigation component")
            }
        }
    }
}
Parameters
navigationSuite: @Composable () -> Unit

the navigation component to be displayed, typically NavigationSuite
state: NavigationSuiteScaffoldState = rememberNavigationSuiteScaffoldState()

the NavigationSuiteScaffoldState of this navigation suite scaffold layout
layoutType: NavigationSuiteType = NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(WindowAdaptiveInfoDefault)

the current NavigationSuiteType. Defaults to NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo
content: @Composable () -> Unit = {}

the content of your screen

rememberNavigationSuiteScaffoldState

Cmn 
@Composable
fun rememberNavigationSuiteScaffoldState(
    initialValue: NavigationSuiteScaffoldValue = NavigationSuiteScaffoldValue.Visible
): NavigationSuiteScaffoldState

Create and remember a NavigationSuiteScaffoldState