NavigationBar

NavigationBar is a bottom navigation bar component in COUI, used to create navigation menus fixed at the bottom of applications. It supports 2 to 5 navigation items, offering different display modes (icon only, text only, icon and text, icon with selected label).

FloatingNavigationBar is a floating-style bottom navigation bar component, also supporting 2 to 5 navigation items, showing icons only.

These components are typically used in conjunction with the Scaffold component to maintain consistent layout and behavior across different pages in the application.

Import

kotlin

import io.github.suqi8.coui.kmp.basic.NavigationBar
import io.github.suqi8.coui.kmp.basic.NavigationBarItem
import io.github.suqi8.coui.kmp.basic.FloatingNavigationBar
import io.github.suqi8.coui.kmp.basic.FloatingNavigationBarItem
import io.github.suqi8.coui.kmp.basic.NavigationBarDisplayMode
import io.github.suqi8.coui.kmp.basic.NavigationItem

Basic Usage

NavigationBar

The NavigationBar component can be used to create bottom navigation menus fixed to the bottom:

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val items = listOf("Home", "Profile", "Settings")
val icons = listOf(COUIIcons.VerticalSplit, COUIIcons.Contacts, COUIIcons.Settings)

Scaffold(
    bottomBar = {
        NavigationBar {
            items.forEachIndexed { index, label ->
                NavigationBarItem(
                    selected = selectedIndex == index,
                    onClick = { selectedIndex = index },
                    icon = icons[index],
                    label = label
                )
            }
        }
    }
)

FloatingNavigationBar

The FloatingNavigationBar component can be used to create floating navigation menus at the bottom:

kotlin

var selectedIndex by remember { mutableStateOf(0) }
val items = listOf("Home", "Profile", "Settings")
val icons = listOf(COUIIcons.VerticalSplit, COUIIcons.Contacts, COUIIcons.Settings)

Scaffold(
    bottomBar = {
        FloatingNavigationBar {
            items.forEachIndexed { index, label ->
                FloatingNavigationBarItem(
                    selected = selectedIndex == index,
                    onClick = { selectedIndex = index },
                    icon = icons[index],
                    label = label
                )
            }
        }
    }
)

Component States

Selected State

NavigationBarItem follows the COUI tab navigation state model: the selected item shows the icon and label at full label color, unselected items are dimmed, and the icon cross-fades between the two states over 180ms while the label color switches instantly. Labels always use medium font weight; pressing an unselected item previews the selected icon color. FloatingNavigationBarItem highlights the icon when selected.

Properties

NavigationBar Properties

Property Name	Type	Description	Default Value	Required
modifier	Modifier	Modifier applied to the nav bar	Modifier	No
color	Color	Background color of the nav bar	COUITheme.colorScheme.background	No
showDivider	Boolean	Show top divider line or not	true	No
defaultWindowInsetsPadding	Boolean	Apply default window insets padding	true	No
mode	NavigationBarDisplayMode	Display mode for items	NavigationBarDisplayMode.IconAndText	No
content	@Composable RowScope.()	The content of the nav bar	-	Yes

NavigationBarItem Properties

Property Name	Type	Description	Default Value	Required
selected	Boolean	Whether the item is selected	-	Yes
onClick	() -> Unit	Callback when the item is clicked	-	Yes
icon	ImageVector	Icon of the item	-	Yes
label	String	Label of the item	-	Yes
modifier	Modifier	Modifier applied to the item	Modifier	No
enabled	Boolean	Whether the item is enabled	true	No

FloatingNavigationBar Properties

Property Name	Type	Description	Default Value	Required
modifier	Modifier	Modifier applied to the nav bar	Modifier	No
color	Color	Background color of the nav bar	COUITheme.colorScheme.surfaceContainer	No
cornerRadius	Dp	Corner radius of the nav bar	FloatingToolbarDefaults.CornerRadius	No
horizontalAlignment	Alignment.Horizontal	Horizontal alignment within its parent	CenterHorizontally	No
horizontalOutSidePadding	Dp	Horizontal padding outside the nav bar	FloatingNavigationBarDefaults.HorizontalOutSidePadding	No
shadowElevation	Dp	The shadow elevation of the nav bar	FloatingNavigationBarDefaults.ShadowElevation	No
showDivider	Boolean	Show divider line around the nav bar	false	No
defaultWindowInsetsPadding	Boolean	Apply default window insets padding	true	No
content	@Composable () -> Unit	The content of the nav bar	-	Yes

FloatingNavigationBarItem Properties

Property Name	Type	Description	Default Value	Required
selected	Boolean	Whether the item is selected	-	Yes
onClick	() -> Unit	Callback when the item is clicked	-	Yes
icon	ImageVector	Icon of the item	-	Yes
label	String	Label of the item	-	Yes
modifier	Modifier	Modifier applied to the item	Modifier	No
enabled	Boolean	Whether the item is enabled	true	No

NavigationBarDefaults Object

The NavigationBarDefaults object provides default values for NavigationBar and NavigationBarItem components.

Constants

Constant Name	Type	Description	Default Value
ItemHeight	Dp	Item cell height	56.dp
HorizontalPadding	Dp	Horizontal padding at both edges of the bar	12.dp
ItemHorizontalPadding	Dp	Horizontal padding inside each item cell	2.dp
IconSize	Dp	Icon size	24.dp
IconTopPadding	Dp	Top padding for the icon	9.dp
LabelBottomPadding	Dp	Bottom padding for the label	7.dp
LabelFontSize	TextUnit	Label font size	10.sp
TextFontSize	TextUnit	Text font size (TextOnly mode)	14.sp
IconFadeDurationMillis	Int	Icon cross-fade duration between states	180

FloatingNavigationBarDefaults Object

The FloatingNavigationBarDefaults object provides default values for FloatingNavigationBar and FloatingNavigationBarItem components.

Constants

Constant Name	Type	Description	Default Value
HorizontalOutSidePadding	Dp	Horizontal outside padding	36.dp
ShadowElevation	Dp	Shadow elevation	1.dp
HorizontalPadding	Dp	Horizontal padding inside the bar	12.dp
ItemSpacing	Dp	Spacing between items	12.dp
IconSize	Dp	Icon size	28.dp
IconPadding	Dp	Padding around the icon	10.dp
SelectedPressedAlpha	Float	Alpha for selected pressed item	0.5f
UnselectedPressedAlpha	Float	Alpha for unselected pressed item	0.6f
UnselectedAlpha	Float	Alpha for unselected item	0.4f

NavigationBarDisplayMode Enum

Value	Description
IconAndText	Show both icon and text
IconOnly	Show icon only
TextOnly	Show text only
IconWithSelectedLabel	Show icon always, show text only when selected

The display mode set on NavigationBar is delivered to its items through the LocalNavigationBarDisplayMode composition local. FloatingNavigationBar has no mode parameter — its items always show icons only.

NavigationItem Properties

NavigationItem is a convenience data class for holding a navigation item's label and icon.

Property Name	Type	Description	Default Value	Required
label	String	Label of the item	-	Yes
icon	ImageVector	Icon of the item	-	Yes

Advanced Usage

NavigationBar

Custom Colors

kotlin

NavigationBar(
    color = Color.Red.copy(alpha = 0.3f)
) {
    // ... items ...
}

Without Divider

kotlin

NavigationBar(
    showDivider = false
) {
    // ... items ...
}

Handling Window Insets

kotlin

NavigationBar(
    defaultWindowInsetsPadding = false // Handle window insets padding manually
) {
    // ... items ...
}

Display Modes

kotlin

NavigationBar(
    // IconAndText (default) / IconOnly / TextOnly / IconWithSelectedLabel
    mode = NavigationBarDisplayMode.IconWithSelectedLabel
) {
    // ... items ...
}

FloatingNavigationBar

Custom Color and Corner Radius

kotlin

FloatingNavigationBar(
    color = COUITheme.colorScheme.primaryContainer,
    cornerRadius = 28.dp
) {
    // ... items ...
}

Custom Alignment and Padding

kotlin

FloatingNavigationBar(
    horizontalAlignment = Alignment.Start, // Align to start
    horizontalOutSidePadding = 16.dp // Set outside padding
) {
    // ... items ...
}

Divider and Shadow

kotlin

FloatingNavigationBar(
    showDivider = true, // Draw a thin divider ring around the bar
    shadowElevation = 0.dp // Disable the drop shadow
) {
    // ... items ...
}

Using NavigationBar

kotlin

val pages = listOf("Home", "Profile", "Settings")
val icons = listOf(COUIIcons.VerticalSplit, COUIIcons.Contacts, COUIIcons.Settings)
var selectedIndex by remember { mutableStateOf(0) }

Scaffold(
    bottomBar = {
        NavigationBar {
            pages.forEachIndexed { index, label ->
                NavigationBarItem(
                    selected = selectedIndex == index,
                    onClick = { selectedIndex = index },
                    icon = icons[index],
                    label = label
                )
            }
        }
    }
) { paddingValues ->
    // Content area needs to consider padding
    Box(
        modifier = Modifier
            .fillMaxSize()
            .padding(paddingValues),
        contentAlignment = Alignment.Center
    ) {
        Text(
            text = "Current Page: ${pages[selectedIndex]}",
            style = COUITheme.textStyles.title1
        )
    }
}

Using FloatingNavigationBar

kotlin

val pages = listOf("Home", "Profile", "Settings")
val icons = listOf(COUIIcons.VerticalSplit, COUIIcons.Contacts, COUIIcons.Settings)
var selectedIndex by remember { mutableStateOf(0) }

Scaffold(
    bottomBar = {
        FloatingNavigationBar {
            pages.forEachIndexed { index, label ->
                FloatingNavigationBarItem(
                    selected = selectedIndex == index,
                    onClick = { selectedIndex = index },
                    icon = icons[index],
                    label = label
                )
            }
        }
    }
) { paddingValues ->
    // Content area needs to consider padding
    Box(
        modifier = Modifier
            .fillMaxSize()
            .padding(paddingValues),
        contentAlignment = Alignment.Center
    ) {
        Text(
            text = "Current Page: ${pages[selectedIndex]}",
            style = COUITheme.textStyles.title1
        )
    }
}

Changelog

Last edited 9 days ago

View full history

NavigationBar ​

Import ​

Basic Usage ​

NavigationBar ​

FloatingNavigationBar ​

Component States ​

Selected State ​

Properties ​

NavigationBar Properties ​

NavigationBarItem Properties ​

FloatingNavigationBar Properties ​

FloatingNavigationBarItem Properties ​

NavigationBarDefaults Object ​

Constants ​

FloatingNavigationBarDefaults Object ​

Constants ​

NavigationBarDisplayMode Enum ​

NavigationItem Properties ​

Advanced Usage ​

NavigationBar ​

Custom Colors ​

Without Divider ​

Handling Window Insets ​

Display Modes ​

FloatingNavigationBar ​

Custom Color and Corner Radius ​

Custom Alignment and Padding ​

Divider and Shadow ​

Using with Page Navigation (Using Scaffold) ​

Using NavigationBar ​

Using FloatingNavigationBar ​

Changelog

NavigationBar

Import

Basic Usage

NavigationBar

FloatingNavigationBar

Component States

Selected State

Properties

NavigationBar Properties

NavigationBarItem Properties

FloatingNavigationBar Properties

FloatingNavigationBarItem Properties

NavigationBarDefaults Object

Constants

FloatingNavigationBarDefaults Object

Constants

NavigationBarDisplayMode Enum

NavigationItem Properties

Advanced Usage

NavigationBar

Custom Colors

Without Divider

Handling Window Insets

Display Modes

FloatingNavigationBar

Custom Color and Corner Radius

Custom Alignment and Padding

Divider and Shadow

Using with Page Navigation (Using Scaffold)

Using NavigationBar

Using FloatingNavigationBar