Tab Group

A foundational component used to create tab groups for navigation in Jetpack Compose and Compose Multiplatform.

Comes with accessibility and keyboard navigation baked in.

Installation

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.composables:core:1.37.0")
}

Basic Example

To create a tab group, use the TabGroup component.

The TabList component hosts the tabs. For each tab include its contents within a TabPanel with the same key as the tab.

It is important to pass an ordered list of the keys in the rememberTabGroupState(). This order is used for cycling through tabs using the keyboard.

val categories = listOf("Trending", "Latest", "Popular")

val state = rememberTabGroupState(
    selectedTab = categories.first(), 
    orderedTabs = categories
)

TabGroup(state = state) {
    TabList {
        categories.forEach { key ->
            Tab(key = key) {
                Text("Tab $key")
            }
        }
    }

    categories.forEach { key ->
        TabPanel(key = key) {
            Text("Content for $key")
        }
    }
}

Styling

Every component in Compose Unstyled is renderless. They handle all UX pattern logic, internal state, accessibility (according to ARIA standards), and keyboard interactions for you, but they do not render any UI to the screen.

This is by design so that you can style your components exactly to your needs.

Most of the time, styling is done using Modifiers of your choice. However, sometimes this is not enough due to the order of the Modifiers affecting the visual outcome.

For such cases we provide specific styling parameters.

Code Example

Disabling a Tab

You can disable a tab by setting the enabled parameter to false in the Tab component.

val state = rememberTabGroupState(selectedTab = "Tab 2", orderedTabs = listOf("Tab 1", "Tab 2", "Tab 3"))

TabGroup(state = state) {
    TabList {
        Tab(key = "Tab 1", enabled = false, modifier = Modifier.alpha(0.4f)) {
            Text("Tab 1")
        }
        Tab(key = "Tab 2") {
            Text("Tab 2")
        }
        Tab(key = "Tab 3") {
            Text("Tab 3")
        }
    }

    TabPanel(key = "Tab 1") {
        Text("Contents 1")
    }
    TabPanel(key = "Tab 2") {
        Text("Contents 2")
    }
    TabPanel(key = "Tab 3") {
        Text("Contents 3")
    }
}

Displaying Tabs Vertically

To display tabs vertically, wrap them into a Column. Make sure to pass Vertical to the orientation parameter of the TabList. This will update the keyboard handling so that users can cycle through tabs by pressing the up and down keys:

val state = rememberTabGroupState(selectedTab = "Tab 2", orderedTabs = listOf("Tab 1", "Tab 2", "Tab 3"))

TabGroup(state = state) {
    TabList(orientation = Orientation.Vertical) {
        Column {
            Tab(key = "Tab 1") {
                Text("Tab 1")
            }
            Tab(key = "Tab 2") {
                Text("Tab 2")
            }
            Tab(key = "Tab 3") {
                Text("Tab 3")
            }
        }
    }

    TabPanel(key = "Tab 1") {
        Text("Contents 1")
    }
    TabPanel(key = "Tab 2") {
        Text("Contents 2")
    }
    TabPanel(key = "Tab 3") {
        Text("Contents 3")
    }
}

Specifying the Default Tab

Specify the default tab by setting the selectedTab parameter in rememberTabGroupState.

val state = rememberTabGroupState(selectedTab = "Tab 2", orderedTabs = listOf("Tab 1", "Tab 2", "Tab 3"))

TabGroup(state = state) {
    TabList {
        Tab(key = "Tab 1", enabled = false) {
            Text("Tab 1")
        }
        Tab(key = "Tab 2") {
            Text("Tab 2")
        }
        Tab(key = "Tab 3") {
            Text("Tab 3")
        }
    }

    TabPanel(key = "Tab 1") {
        Text("Content for Tab 1")
    }
    TabPanel(key = "Tab 2") {
        Text("Content for Tab 2")
    }
    TabPanel(key = "Tab 3") {
        Text("Content for Tab 3")
    }
}

Changing Tabs Manually

You can change tabs programmatically by setting the selectedTab property of the TabGroupState.

val state = rememberTabGroupState(selectedTab = "Tab 2", orderedTabs = listOf("Tab 1", "Tab 2", "Tab 3"))

Button(onClick = { state.selectedTab = "Tab 3" }) {
    Text("Go to Tab 3")
}

TabGroup(state = state) {
    TabList {
        Tab(key = "Tab 1", enabled = false) {
            Text("Tab 1")
        }
        Tab(key = "Tab 2") {
            Text("Tab 2")
        }
        Tab(key = "Tab 3") {
            Text("Tab 3")
        }
    }

    TabPanel(key = "Tab 1") {
        Text("Content for Tab 1")
    }
    TabPanel(key = "Tab 2") {
        Text("Content for Tab 2")
    }
    TabPanel(key = "Tab 3") {
        Text("Content for Tab 3")
    }
}

Keyboard Interactions

For the tab list:

Component API

TabGroupState

rememberTabGroupState

TabGroup

TabList

Tab

TabPanel