Skip to content

Extra

NavigationRail

A FormaUI navigation rail — top-level destination switching for tablet/desktop-width screens, delegating to Material 3's NavigationRail.

dev.formaui.components.navigation

with headeritem with numeric badgeitem with dot badge

Preview

This toggle is site chrome only — the preview has its own light/dark switch inside.

Live preview

Live preview — ~37 MB development build

Usage

var selected by remember { mutableIntStateOf(0) }
FormaNavigationRail(
    header = { Text("+") },
) {
    FormaNavigationRailItem(selected = selected == 0, onClick = { selected = 0 }, icon = { Text("🏠") }, label = "Home")
    FormaNavigationRailItem(selected = selected == 1, onClick = { selected = 1 }, icon = { Text("🔔") }, label = "Alerts", badgeCount = 12)
    FormaNavigationRailItem(selected = selected == 2, onClick = { selected = 2 }, icon = { Text("👤") }, label = "Profile", showBadgeDot = true)
}

FormaNavigationRail

Vertical rail pinned to the start edge, with an optional header slot (typically a FAB or logo) above the items.

modifierTypeModifierDefaultModifierDescriptionthe Modifier applied to the rail.
containerColorTypeColorDefaultNavigationRailDefaults.ContainerColorDescriptionthe rail's background color (defaults to the M3 navigation-rail container, themed by FormaTheme).
contentColorTypeColorDefaultcontentColorFor(containerColor)Descriptionthe preferred content color for items (defaults to the color matching containerColor).
headerType@Composable (ColumnScope.() -> Unit)?DefaultnullDescriptionoptional content shown above the items (typically a FAB or a logo).
contentrequiredType@Composable ColumnScope.() -> UnitDefaultrequiredDescriptionthe rail's items, laid out in a ColumnScope (typically 3-7 FormaNavigationRailItems).

FormaNavigationRailItem

A single rail destination with built-in per-item badge support (numeric badgeCount or dot via showBadgeDot); takes no scope receiver.

selectedrequiredTypeBooleanDefaultrequiredDescriptionwhether this item is the current destination.
onClickrequiredType() -> UnitDefaultrequiredDescriptioncalled when the item is tapped.
iconrequiredType@Composable () -> UnitDefaultrequiredDescriptionthe item's icon (supply a contentDescription on it for accessibility).
modifierTypeModifierDefaultModifierDescriptionthe Modifier applied to the item.
labelTypeString?DefaultnullDescriptionoptional text label shown under the icon.
enabledTypeBooleanDefaulttrueDescriptionwhether the item is interactive.
badgeCountTypeInt?DefaultnullDescriptionoptional unread count to show as a numeric badge on the icon.
showBadgeDotTypeBooleanDefaultfalseDescriptionwhen true and badgeCount is null, shows a dot badge on the icon.
alwaysShowLabelTypeBooleanDefaulttrueDescriptionwhether the label is shown even when the item is unselected.
colorsTypeNavigationRailItemColors?DefaultnullDescriptionthe item colors — icon, label, and selection-indicator colors for the selected, unselected, and disabled states. Defaults to the M3 defaults, themed by FormaTheme.
labelTextStyleTypeTextStyle?DefaultnullDescriptionoptional TextStyle override for label, merged on top of the M3 label style.

Accessibility

48dp touch target and selection semantics come from Material 3's NavigationRailItem; supply a contentDescription on each item's icon.