At the time, there was no built-in composable to display tooltips and there were several alternative solutions circling online. The problem with those solutions was that once Jetpack Compose released newer versions, those solutions might break. So it wasn’t ideal and the community was left hoping that sometime in the future, support would be added for tooltips.

I’m glad to say that since version 1.1.0 of Compose Material 3, we now have built in tooltip support. 👏

While this in itself is great, more than a year has passed since that version was released. And with subsequent versions, the API related to tooltips changed drastically as well.

If you go over the changelog, you will see how the public and internal APIs have changed. So bear in mind, that when you read this article, things may have continued to change as everything related to Tooltips is still marked by the annotation ExperimentalMaterial3Api::class.

❗️ The version of material 3 used for this article is 1.2.1, which was released on March 6th, 2024

Tooltip Types

We now have support for two different types of tooltips:

1. Plain tooltip

2. Rich media tooltip

Plain Tooltip

You can use the first kind to provide information about an icon button that wouldn’t be clear otherwise. For example, you can use a plain tooltip to indicate to a user what the icon button represents.

To add a tooltip to your application, you use the TooltipBox composable. This composable takes several arguments:

fun TooltipBox(
    positionProvider: PopupPositionProvider,
    tooltip: @Composable TooltipScope.() -> Unit,
    state: TooltipState,
    modifier: Modifier = Modifier,
    focusable: Boolean = true,
    enableUserInput: Boolean = true,
    content: @Composable () -> Unit,
)

Some of these should be familiar to you if you have used Composables before. I’ll highlight the ones that have a specific use case here:

• positionProvider - Of PopupPositionProvider type, and is used to calculate the position of the tooltip.

• tooltip - This is where you can design the UI of how the tooltip will look like.

• state - This holds the state that is associated with a specific Tooltip instance. It exposes methods like showing/dismissing the tooltip and when instantiating an instance of one, you can declare if the tooltip should be persistent or not (meaning if it should keep displaying on the screen until a user performs a click action outside the tooltip).

• content - This is the UI that the tooltip will display above/below.

Here is an example of instantiating a BasicTooltipBox with all the relevant arguments filled in:

@OptIn(ExperimentalFoundationApi::class, ExperimentalMaterial3Api::class)
@Composable
fun BasicTooltip() {
    val tooltipPosition = TooltipDefaults.rememberPlainTooltipPositionProvider()
    val tooltipState = rememberBasicTooltipState(isPersistent = false)

    BasicTooltipBox(positionProvider = tooltipPosition,
        tooltip =  { Text("Hello World") } ,
        state = tooltipState) {
        IconButton(onClick = { }) {
            Icon(imageVector = Icons.Filled.Favorite, 
                 contentDescription = "Your icon's description")
        }
    }
}

Jetpack Compose has a built in class called TooltipDefaults. You can use this class to help you instantiate arguments that make up a TooltipBox. For instance, you could use TooltipDefaults.rememberPlainTooltipPositionProvider to correctly position the tooltip in relation to the anchor element.

Rich Tooltip

A rich media tooltip takes more space than a plain tooltip and can be used to provide more context about the functionality of an icon button. When the tooltip is shown, you can add buttons and links to it to provide further explanation or definitions.

It is instantiated in a similar way as a plain tooltip, inside of a TooltipBox, but you use the RichTooltip composable.

TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {
                        Text("This is where a description would go.")
                  }
        },
        state = tooltipState) {
        IconButton(onClick = {
            /* Icon button's click event */
        }) {
            Icon(imageVector = tooltipIcon,
                contentDescription = "Your icon's description",
                tint = iconColor)
        }
    }

A few things to notice about a Rich tooltip:

1. A Rich tooltip has support for a caret.

2. You can add an action (that is, a button) to the tooltip to give users an option to find out more information.

3. You can add logic to dismiss the tooltip.

Edge Cases

When you choose to mark your tooltip state as persistent, it means that once the user interacts with the UI that shows your tooltip, it will stay visible until the user presses anywhere else on the screen.

If you looked at the example of a Rich tooltip from above, you might have noticed that we have added a button to dismiss the tooltip once it’s clicked.

There is a problem that happens once a user presses that button. Since the dismiss action is performed on the tooltip, if a user wants to perform another long press on the UI item that invokes this tooltip, the tooltip won’t be shown again. This means that the state of the tooltip is persistent on it being dismissed. So, how do we go about and resolve this?

In order to “reset” the state of the tooltip, we have to call the onDispose method that is exposed through the tooltip state. Once we do that, the tooltip state is reset and the tooltip will be shown again when the user performs a long press on the UI item.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun RichTooltip() {
    val tooltipPosition = TooltipDefaults.rememberRichTooltipPositionProvider()
    val tooltipState = rememberTooltipState(isPersistent = true)
    val scope = rememberCoroutineScope()

    TooltipBox(positionProvider = tooltipPosition,
        tooltip = {
                  RichTooltip(
                      title = { Text("RichTooltip") },
                      caretSize = TooltipDefaults.caretSize,
                      action = {
                          TextButton(onClick = {
                              scope.launch {
                                  tooltipState.dismiss()
                                  tooltipState.onDispose()  /// <---- HERE
                              }
                          }) {
                              Text("Dismiss")
                          }
                      }
                  ) {

                  }
        },
        state = tooltipState) {
        IconButton(onClick = {  }) {
            Icon(imageVector = Icons.Filled.Call, contentDescription = "Your icon's description")
        }
    }
}

Another scenario where the tooltip state does not reset is if instead of calling ourselves for the dismiss method per a user’s action, the user clicks outside of the tooltip, causing it to be dismissed. This calls the dismiss method behind the scenes and the tooltip state is set to dismissed. Long pressing on the UI element to see our tooltip again will result in nothing.

Our logic that calls the tooltip’s onDispose method does not get triggered, so how can we reset the tooltip’s state?

Currently, I haven’t been able to figure this out. It might be related to the tooltip’s MutatorMutex. Maybe with upcoming releases, there will be an API for this. I did notice that if other tooltips are present on the screen and they are pressed, this resets the previously clicked upon tooltip.

If you would like to see the code featured here, you can go to this GitHub repository

If you would like to see tooltips in an application, you can check it out here.

References

• Material3 Tooltip Overview

• Tooltip Defaults

• Tooltip Source Code

If your application depends on getting the user’s location, you want to ensure that the user has a good experience when the application requests this info. So it's crucial to handle all the edge cases and allow the user to select the option the they're most comfortable with.

With Jetpack Compose, the logic associated with getting the user’s location has changed a bit, and it’s important to know the in’s and out’s of how it can be done.

As with most things, there is a library you can use to handle getting permissions. It’s from Accompanist (read Google) and you can find it here. But you are here to learn how to do things yourself, right? So read on. 🕵️‍♀️

Before we get into the code and the logic, it is important to understand that requesting a permission from a user is a path that can have many decision points. As such, it is best described by having states that represent the current status of the permission (approved/rejected/denied) and the current status of the operating system.

The diagram below illustrates this flow:

Later on in this article, you will see how we will represent these states in variables in our code.

Save Our Souls (S.O.S)

Before we get to the logic of asking for a permission, we’ll take care of the boilerplate around it. As always, add the necessary permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Then, we’ll create a composable screen where we ask for the necessary location permissions. The first step in this screen is to check whether the user has previously granted the required permissions. You can do this with something that is not new to Jetpack Compose – using the checkSelfPermission method:

val locationPermissionsAlreadyGranted = ContextCompat.checkSelfPermission(
            this,
            Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED

If the permission is not granted, we have to request it. We will use the rememberLauncherForActivityResult object to do this. This allows us in Jetpack Compose to get a result from an Activity.

val locationPermissions = arrayOf(
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION)

val locationPermissionLauncher = rememberLauncherForActivityResult(
                contract = ActivityResultContracts.RequestMultiplePermissions(),
                onResult = { permissions ->
                    val permissionsGranted = permissions.values.reduce { acc, isPermissionGranted ->
                        acc && isPermissionGranted
                    }

                    if (!permissionsGranted) {
                       //Logic when the permissions were not granted by the user
                    }
                })

The arguments that we need to pass to rememberLauncherForActivityResult are:

1. An ActivityResultContract – specifies the input of the activity and the output
2. onResult – a callback when the result is received

In the code snippet above, we are using a multiple permissions contract, since we are requesting several location permissions. There is also a contract for requesting just one permission, ActivityResultContracts.RequestPermission().

This piece of code doesn’t not run immediately as we need to request the permissions. To do that we use the launch method to start the activity:

locationPermissionLauncher.launch(locationPermissions)

In the case the user gave all or several of the required permissions, we can continue the logic of the application.

But, if the user did not approve any of the permissions, we need to find a way to make the user understand why these permissions are necessary.

Explaining the Rationale

In case the user declined the permission, but did not select the “Deny And Don’t Ask Me Again” option, we have a way of giving the user a brief explanation on why they should grant the required permission(s).

To figure out if we should present this rationale, we use the shouldShowRequestPermissionRationale from the Activity class:

val shouldShowPermissionRationale: Boolean = shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)

Once we know that we can display this explanation, there are two ways to go about it:

1. We can present it to the user with an AlertDialog
2. We can use the Snackbar

Presenting an alert dialog is pretty straightforward. All we have to do is make sure we describe clearly to the user why it is required to approve this permission:

@Composable
    fun ShowLocationPermissionRationale() {
        AlertDialog(
            onDismissRequest = {
               //Logic when dismiss happens
            },
        title = {
            Text("Permission Required")
                },
        text = {
            Text("You need to approve this permission in order to...")
        },
        confirmButton = {
            TextButton(onClick = {
              //Logic when user confirms to accept permissions
            }) {
                Text("Confirm")
            }
        },
        dismissButton = {
            TextButton(onClick = {
              //Logic when user denies to accept permissions
            }) {
                Text("Deny")
            }
        })
    }

If we want to present the Snackbar, we need to be aware that we have to use a Scaffold container since that is the only container that supports showing a Snackbar. If we don’t use one, a Snackbar won’t appear.

Below is a snippet that shows you how to do this:

val scope = rememberCoroutineScope()
val snackbarHostState = remember { SnackbarHostState() }

Scaffold(snackbarHost = {
        SnackbarHost(hostState = snackbarHostState)
    }) { contentPadding ->
        if (shouldShowPermissionRationale) {
            LaunchedEffect(key1 = shouldShowPermissionRationale, block = {
                scope.launch {
                    val userAction = snackbarHostState.showSnackbar(
                        message ="Please authorize location permissions",
                        actionLabel = "Approve",
                        duration = SnackbarDuration.Indefinite,
                        withDismissAction = true
                    )
                    when (userAction) {
                        SnackbarResult.ActionPerformed -> {
                            //User approved to grant the permission
                            //Ask for permissions again
                        }
                        SnackbarResult.Dismissed -> {
                            //User dismissed snackbar
                        }
                    }
                }
            })
        }
}

We allowed the Snackbar itself to be dismissible using the withDismissAction attribute and listened in to the action performed by the user.

Lifecycle Observer

One thing we have glossed over is the fact that we need to make sure our permission request adheres to the composable lifecycle. This means that once a user chooses their preferences regarding the permission request, we need the UI to adapt accordingly.

If you try and put the code above inside the activity’s onCreate method, you will be surprised with the outcome, since the application will crash with the following exception:

java.lang.IllegalStateException: Launcher has not been initialized

This is because Composable functions are supposed to be side effect free. What is a side effect? According to Google’s documentation it is:

… a change to the state of the app that happens outside the scope of a composable function

So, in our use case, launching an activity for the permissions is the side effect happening here.

To circumvent this scenario, we need to use one of the side effect options. Since we don’t want to ask the user for permissions without remembering what their choices were previously, we can’t use the general SideEffect. And LaunchedEffect is used for calling suspend methods inside of a Composable, which is not our use case here.

So we are left with DisposableEffect. Reading the documentation, we can see that DisposableEffect can be combined with Lifecycle events, which is what we are after.

val lifecycleOwner = LocalLifecycleOwner.current
            DisposableEffect(key1 = lifecycleOwner, effect = {
                val observer = LifecycleEventObserver { _, event ->
                    if (event == Lifecycle.Event.ON_START && !locationPermissionsAlreadyGranted) {
                        locationPermissionLauncher.launch(locationPermissions)
                       }
                    }
                    lifecycleOwner.lifecycle.addObserver(observer)
                    onDispose {
                        lifecycleOwner.lifecycle.removeObserver(observer)
                    }
                }
            )

In the code snippet above, we are adding a lifecycle observer that runs only in the case of the onStart lifecycle event. We also combine it with the boolean we have declared at the start of this section, locationPermissionsAlreadyGranted. This is so we won’t show the dialog for asking permissions if they are already granted.

As with all lifecycle observers, we need to remove our observer once the composition ends. We have that logic inside DisposableEffect’s onDispose clause.

Location Not Found

The last case we need to deal with is when the user chooses the “Deny And Don’t Ask Me Again” option. When this happens, we cannot ask the user to grant the required permissions.

The only way the user can revert their choice is to go to the settings screen of our application and change the permissions there. So we need to direct the user to go there.

To open the settings screen of our application, we need to use an intent with the action of ACTION_APPLICATION_DETAILS_SETTINGS.

Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)).also {
            startActivity(it)
        }

Taking the logic above, we can add it to our code when we know that the user has chosen to deny the permissions and not be asked again. This happens inside our request for permissions when the user has not granted the permissions and the option to show the rationale is false.

Location Confirmed

If we take everything we discussed in this article and put it inside one file, we will get the following code:

class MainActivity : ComponentActivity() {

    @OptIn(ExperimentalMaterial3Api::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {

            var locationPermissionsGranted by remember { mutableStateOf(areLocationPermissionsAlreadyGranted()) }
            var shouldShowPermissionRationale by remember {
                mutableStateOf(
                    shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)
                )
            }

            var shouldDirectUserToApplicationSettings by remember {
                mutableStateOf(false)
            }

            var currentPermissionsStatus by remember {
                mutableStateOf(decideCurrentPermissionStatus(locationPermissionsGranted, shouldShowPermissionRationale))
            }

            val locationPermissions = arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.ACCESS_COARSE_LOCATION
            )

            val locationPermissionLauncher = rememberLauncherForActivityResult(
                contract = ActivityResultContracts.RequestMultiplePermissions(),
                onResult = { permissions ->
                    locationPermissionsGranted = permissions.values.reduce { acc, isPermissionGranted ->
                        acc && isPermissionGranted
                    }

                    if (!locationPermissionsGranted) {
                        shouldShowPermissionRationale =
                            shouldShowRequestPermissionRationale(Manifest.permission.ACCESS_COARSE_LOCATION)
                    }
                    shouldDirectUserToApplicationSettings = !shouldShowPermissionRationale && !locationPermissionsGranted
                    currentPermissionsStatus = decideCurrentPermissionStatus(locationPermissionsGranted, shouldShowPermissionRationale)
                })

            val lifecycleOwner = LocalLifecycleOwner.current
            DisposableEffect(key1 = lifecycleOwner, effect = {
                val observer = LifecycleEventObserver { _, event ->
                    if (event == Lifecycle.Event.ON_START &&
                        !locationPermissionsGranted &&
                        !shouldShowPermissionRationale) {
                        locationPermissionLauncher.launch(locationPermissions)
                    }
                }
                lifecycleOwner.lifecycle.addObserver(observer)
                onDispose {
                    lifecycleOwner.lifecycle.removeObserver(observer)
                    }
                }
            )

            val scope = rememberCoroutineScope()
            val snackbarHostState = remember { SnackbarHostState() }

            LocationPermissionsTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    Scaffold(snackbarHost = {
                        SnackbarHost(hostState = snackbarHostState)
                    }) { contentPadding ->
                        Column(modifier = Modifier.fillMaxSize(),
                        verticalArrangement = Arrangement.Center,
                        horizontalAlignment = Alignment.CenterHorizontally){
                            Text(modifier = Modifier
                                .padding(contentPadding)
                                .fillMaxWidth(),
                                text = "Location Permissions",
                                textAlign = TextAlign.Center)
                            Spacer(modifier = Modifier.padding(20.dp))
                            Text(modifier = Modifier
                                .padding(contentPadding)
                                .fillMaxWidth(),
                                text = "Current Permission Status: $currentPermissionsStatus",
                                textAlign = TextAlign.Center,
                                fontWeight = FontWeight.Bold
                            )
                        }
                        if (shouldShowPermissionRationale) {
                            LaunchedEffect(Unit) {
                                scope.launch {
                                    val userAction = snackbarHostState.showSnackbar(
                                        message ="Please authorize location permissions",
                                        actionLabel = "Approve",
                                        duration = SnackbarDuration.Indefinite,
                                        withDismissAction = true
                                    )
                                    when (userAction) {
                                        SnackbarResult.ActionPerformed -> {
                                            shouldShowPermissionRationale = false
                                            locationPermissionLauncher.launch(locationPermissions)
                                        }
                                        SnackbarResult.Dismissed -> {
                                            shouldShowPermissionRationale = false
                                        }
                                    }
                                }
                            }
                        }
                        if (shouldDirectUserToApplicationSettings) {
                            openApplicationSettings()
                        }
                    }
                }
            }
        }
    }

    private fun areLocationPermissionsAlreadyGranted(): Boolean {
        return ContextCompat.checkSelfPermission(
            this,
            Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
    }

    private fun openApplicationSettings() {
        Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.fromParts("package", packageName, null)).also {
            startActivity(it)
        }
    }

    private fun decideCurrentPermissionStatus(locationPermissionsGranted: Boolean,
                                              shouldShowPermissionRationale: Boolean): String {
        return if (locationPermissionsGranted) "Granted"
        else if (shouldShowPermissionRationale) "Rejected"
        else "Denied"
    }
}

And this is how it looks like:

I have put all the logic in one file just for the purpose of this article. It is by no means the most esthetic and correct approach to handling the logic with requesting permissions.

You could easily refactor out the logic variables associated with holding the different state of the request for permissions to a view model class that is attached to this screen.

You can see all of the code described in this article by going to this project:

And if you would like to read more of my articles, you can go view them below:

I have also used this logic in an application that you can try out here.

Thank you for reading!

We’ve all done it.

Ain’t nothing like good ol’ tabs to organize content in a complex application. So how do we go about creating a tab layout in Jetpack Compose?

In this tutorial, we’ll go over all of the basics, but also show some things that are more advanced.

How to Create Simple Tabs

To create a tab layout, you need to start with a TabRow. This will be a container element that will hold your tabs.

@Composable
@UiComposable
fun TabRow(
    selectedTabIndex: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor),
    indicator: @Composable @UiComposable (tabPositions: List<TabPosition>) -> Unit = @Composable { tabPositions ->
            TabRowDefaults.Indicator(
                Modifier.tabIndicatorOffset(tabPositions[selectedTabIndex])
            )
        },
    divider: @Composable @UiComposable () -> Unit = @Composable {
            TabRowDefaults.Divider()
        },
    tabs: @Composable @UiComposable () -> Unit
): Unit

• selectedTabIndex indicates the index of the tab that is currently selected
• indicator represents the UI that indicates which tab is currently selected
• divider is a composable that is drawn at the bottom of the TabRow under the indicator
• If you don’t have a need to custom style your tabs, you can use TabRowDefaults as it contains the default values and implementation used for TabRow (you can see it being used inside divider)

Let’s see the usage of TabRow with an example. We will create a simple layout that will have three tabs:

1. Home
2. About
3. Settings

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings")

    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
        }
    }
}

A couple things to pay attention to:

• The TabRow composable holds inside of itself a Tab composable
• After the TabRow composable, we have a when clause to handle what happens when each tab is clicked (in our specific case we are opening different screens)
• We are using a variable called tabIndex to keep track of which Tab is selected

Pretty bland, right?

Let’s spice things up with icons by using the icon attribute of the Tab composable.

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings")

    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                        }
                    }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
        }
    }
}

Looking better, but a question does arise: What if we have more tabs than the screen can show?

Luckily, the answer is simple.

There is an option to make our TabRow scrollable. Instead of using the TabRow element, you can use the ScrollableTabRow composable.

@Composable
@UiComposable
fun ScrollableTabRow(
    selectedTabIndex: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor),
    edgePadding: Dp = TabRowDefaults.ScrollableTabRowPadding,
    indicator: @Composable @UiComposable (tabPositions: List<TabPosition>) -> Unit = @Composable { tabPositions ->
            TabRowDefaults.Indicator(
                Modifier.tabIndicatorOffset(tabPositions[selectedTabIndex])
            )
        },
    divider: @Composable @UiComposable () -> Unit = @Composable {
            TabRowDefaults.Divider()
        },
    tabs: @Composable @UiComposable () -> Unit
): Unit

So if we convert our example from above, we will get this:

@Composable
fun TabScreen() {
    var tabIndex by remember { mutableStateOf(0) }

    val tabs = listOf("Home", "About", "Settings", "More", "Something", "Everything")

    Column(modifier = Modifier.fillMaxWidth()) {
        ScrollableTabRow(selectedTabIndex = tabIndex) {
            tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex == index,
                    onClick = { tabIndex = index },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                            3 -> Icon(imageVector = Icons.Default.Lock, contentDescription = null)
                            4 -> Icon(imageVector = Icons.Default.HeartBroken, contentDescription = null)
                            5 -> Icon(imageVector = Icons.Default.Star, contentDescription = null)
                        }
                    }
                )
            }
        }
        when (tabIndex) {
            0 -> HomeScreen()
            1 -> AboutScreen()
            2 -> SettingsScreen()
            3 -> MoreScreen()
            4 -> SomethingScreen()
            5 -> EverythingScreen()
        }
    }
}

How to Create Tabs with Swiping Enabled

Scrollable tabs are nice, but swiping between tabs is even better. Most users will feel that it's more intuitive to swipe between the tabs rather than clicking on each one. If you look at the documentation, you will notice that there are a few options to go with:

1. The swipeable modifier
2. The detectDragGestures modifier
3. The draggable modifier

Not all of these will help us in achieving our goal, each one for its own reasons. If you don’t want to go through the “hassle” of doing things yourself, there is a library from Accompanist called pager that you can use. It allows you to add the ability to either horizontally or vertically create a row/column that reacts to swipes.

Steps to implement it have been covered already and you can use the resources below to learn how to do it:

• https://johncodeos.com/how-to-create-tabs-with-jetpack-compose/
• https://www.rockandnull.com/jetpack-compose-swipe-pager/

If you are like me and you like to do things for yourself and are up for getting your hands dirty, read on.

Option 1: the Swipeable Modifier

The first thing to know about the swipeable modifier is that it is annotated with the @ExperimentalMaterialApi. This means that this API can change between versions of Jetpack Compose and that it isn’t stable.

Apart from that, we need to go over the mechanism that the swipeable modifier uses. It has 3 building blocks:

1. A swipeable state – Denoting the current state and holding data about any on going swipe or swipe related animation.
2. Anchors – A map of values (Float based) restricting the swipe action from the minimum value to the maximum value. It maps anchor points to swipeable states.
3. Thresholds – A value denoting the difference between two known anchors.

@ExperimentalMaterialApi
fun <T : Any?> Modifier.swipeable(
    state: SwipeableState<T>,
    anchors: Map<Float, T>,
    orientation: Orientation,
    enabled: Boolean = true,
    reverseDirection: Boolean = false,
    interactionSource: MutableInteractionSource? = null,
    thresholds: (from, to) -> ThresholdConfig = { _, _ -> FixedThreshold(56.dp) },
    resistance: ResistanceConfig? = resistanceConfig(anchors.keys),
    velocityThreshold: Dp = VelocityThreshold
): Modifier

Regardless of this API being experimental, it just isn’t meant to be used for the swiping gesture we are seeking.

You can. use this modifier for a switch button that the user can drag between on/off positions (as an example). But what would be our anchors in our example? How do we define the thresholds? The swipe a user performs cannot be constrained between two points. Therefore, we’ll let this one go and move on to detectDragGestures.

Option 2: the detectDragGestures Modifier

As the name implies, this modifier detects the drag gesture, which can be quite similar to swiping.

suspend fun PointerInputScope.detectDragGestures(
    onDragStart: (Offset) -> Unit = { },
    onDragEnd: () -> Unit = { },
    onDragCancel: () -> Unit = { },
    onDrag: (change: PointerInputChange, dragAmount: Offset) -> Unit
): Unit

As you can see, the onDrag callback has two arguments:

1. change – of PointerInputChange type, denoting the change in pointer when dragging
2. dragAmount – of Offset type, denoting the amount dragged in x,y values

This callback is called when:

“… waits for pointer down and touch stop in any direction and then calls onDrag for each drag event.”

The upside to use this modifier instead of the draggable one is that it provides you with information about the change in both x and y coordinates.

The downside of it is that it isn’t going to offer a smooth and elegant solution for swiping. This is because of the amount of times the onDrag callback is triggered.

When a user performs a swipe gesture, the onDrag callback is triggered multiple times. This makes it harder to discern when the “drag” gesture has ended completely.

When experimenting with this, I saw the onDrag callback being triggered three times for each swipe gesture. This won’t be a good fit for our use case so let’s check out the draggable modifier.

Option 3: the Draggable Modifier

Think of this modifier as the stripped down version of the one before. This one measures changes in the UI when the user performs a drag gesture in only one orientation (vertical/horizontal). Since we only care about horizontal swipes, this can be a good option.

fun Modifier.draggable(
    state: DraggableState,
    orientation: Orientation,
    enabled: Boolean = true,
    interactionSource: MutableInteractionSource? = null,
    startDragImmediately: Boolean = false,
    onDragStarted: suspend CoroutineScope.(startedPosition: Offset) -> Unit = {},
    onDragStopped: suspend CoroutineScope.(velocity: Float) -> Unit = {},
    reverseDirection: Boolean = false
): Modifier

Here as well there is no similarity to the two other modifiers and we will point out the things to pay attention to:

• state – Similar to the state in the swipeable modifier, only here we are talking about a drag motion.
• onDragStarted – A callback triggered when the drag motion has begun.
• onDragStopped – A callback triggered when the drag motion has ended.

Unlike detectDragGestures, here onDragStopped is called once for every swipe gesture, making this modifier the best candidate for the job.

It’s implementation as a swipe gesture detector in our example is quite robust, so let’s start with some prerequisites:

1. We will be saving the index of the tab currently being viewed in a view model class
2. This index will be of MutableLiveData so that our composables will be able to recompose when the value is changed
3. Each of our screens will add the draggable modifier to its layout
4. We will need to add the runtime-livedata library as we are going to use the observeAsState method.

We will start with #4.

Go to your application’s build.gradle file and add the following dependency:

implementation "androidx.compose.runtime:runtime-livedata:$compose_version"

where $compose_version is the version of Jetpack Compose you are using.

We have also minimized our previous example to hold three screens instead of six, as the solution works for either case and there is no need to create extra boiler plate.

Below is the view model:

class MainViewModel(application: Application) : AndroidViewModel(application) {

    private val _tabIndex: MutableLiveData<Int> = MutableLiveData(0)
    val tabIndex: LiveData<Int> = _tabIndex
    val tabs = listOf("Home", "About", "Settings")

    fun updateTabIndexBasedOnSwipe(isSwipeToTheLeft: Boolean) {
        _tabIndex.value = when (isSwipeToTheLeft) {
            true -> Math.floorMod(_tabIndex.value!!.plus(1), tabs.size)
            false -> Math.floorMod(_tabIndex.value!!.minus(1), tabs.size)
        }
    }

    fun updateTabIndex(i: Int) {
        _tabIndex.value = i
    }

}

• tabIndex is in charge of holding the currently selected index.
• index is the exposed tabIndex.
• tabs is the list of tab names.
• The method updateTabIndexBasedOnSwipe is triggered when a swipe happens and performs the calculation of where to move the tabIndex to.

Each screen is made up of the same layout:

@Composable
fun AboutScreen(viewModel: MainViewModel) {

    var isSwipeToTheLeft by remember { mutableStateOf(false) }
    val dragState = rememberDraggableState(onDelta = { delta ->
        isSwipeToTheLeft = delta > 0
    })

    Column(modifier = Modifier.fillMaxSize().draggable(
        state = dragState,
        orientation = Orientation.Horizontal,
        onDragStarted = {  },
        onDragStopped = {
            viewModel.updateTabIndexBasedOnSwipe(isSwipeToTheLeft = isSwipeToTheLeft)
        }),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center) {
        Row(modifier = Modifier.align(Alignment.CenterHorizontally)) {
            Text(
                text = "About",
                textAlign = TextAlign.Center,
                fontSize = 20.sp,
                fontWeight = FontWeight.Bold
            )
        }
    }
}

• isSwipeToTheLeft is a Boolean indicating the direction of the swipe.
• dragState holds the state of the drag being performed and updates isSwipeToTheLeft according to the delta.
• When the callback onDragStopped is called, we are calling the exposed viewModel method updateTabIndexBasedOnSwipe.

And finally, our TabLayout:

@Composable
fun TabLayout(viewModel: MainViewModel) {
    val tabIndex = viewModel.tabIndex.observeAsState()
    Column(modifier = Modifier.fillMaxWidth()) {
        TabRow(selectedTabIndex = tabIndex.value!!) {
            viewModel.tabs.forEachIndexed { index, title ->
                Tab(text = { Text(title) },
                    selected = tabIndex.value!! == index,
                    onClick = { viewModel.updateTabIndex(index) },
                    icon = {
                        when (index) {
                            0 -> Icon(imageVector = Icons.Default.Home, contentDescription = null)
                            1 -> Icon(imageVector = Icons.Default.Info, contentDescription = null)
                            2 -> Icon(imageVector = Icons.Default.Settings, contentDescription = null)
                        }
                    }
                )
            }
        }

        when (tabIndex.value) {
            0 -> HomeScreen(viewModel = viewModel)
            1 -> AboutScreen(viewModel = viewModel)
            2 -> SettingsScreen(viewModel = viewModel)
        }
    }
}

• Notice that when a tab is selected, we are updating the currently selected tab in the viewModel with updateTabIndex.

Putting it all together yields:

A few words regarding what we have accomplished. You might have noticed that there is some boilerplate we are adding for each of our screens that results in repetition. Each screen is saving the state of the drag.

To improve on that, we can move the draggableState to the view model, like so:

class MainViewModel(application: Application) : AndroidViewModel(application) {

    private val _tabIndex: MutableLiveData<Int> = MutableLiveData(0)
    val tabIndex: LiveData<Int> = _tabIndex
    val tabs = listOf("Home", "About", "Settings")

    var isSwipeToTheLeft: Boolean = false
    private val draggableState = DraggableState { delta ->
        isSwipeToTheLeft= delta > 0
    }

    private val _dragState = MutableLiveData<DraggableState>(draggableState)
    val dragState: LiveData<DraggableState> = _dragState

    fun updateTabIndexBasedOnSwipe() {
        _tabIndex.value = when (isSwipeToTheLeft) {
            true -> Math.floorMod(_tabIndex.value!!.plus(1), tabs.size)
            false -> Math.floorMod(_tabIndex.value!!.minus(1), tabs.size)
        }
    }

    fun updateTabIndex(i: Int) {
        _tabIndex.value = i
    }

}

And that reduces the boilerplate a bit, since each screen now looks like:

@Composable
fun AboutScreen(viewModel: MainViewModel) {

    Column(modifier = Modifier.fillMaxSize().draggable(
        state = viewModel.dragState.value!!,
        orientation = Orientation.Horizontal,
        onDragStarted = {  },
        onDragStopped = {
            viewModel.updateTabIndexBasedOnSwipe()
        }),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center) {
        Row(modifier = Modifier.align(Alignment.CenterHorizontally)) {
            Text(
                text = "About",
                textAlign = TextAlign.Center,
                fontSize = 20.sp,
                fontWeight = FontWeight.Bold
            )
        }
    }
}

I hope this article gave you the necessary tools to create your own tabs UI in Jetpack Compose.

The example shown above can be found here.

And if you would like to read other articles I have written, you can check them out here.

References:

• Material Design page about Tabs
• Gestures In Jetpack Compose

If you have ever worked with a database or fetching data from a server, this should all be familiar to you. If not, you have come to the right place.

In this tutorial, we will go over:

• How to setup serialization in a Jetpack Compose project
• How to serialize a data class
• How to de-serialize a data class

You might be asking yourself, what’s so special about serialization in Jetpack Compose? In essence, there isn’t a lot of difference than with a regular Kotlin Android project. The only difference is in the setup.

How to Set Everything Up

Each version of Jetpack Compose corresponds with a version of Kotiln that it is compatible with. Each version of the kotlin-serialization library is also compatible with a specific version of Kotlin. So you need to make sure that each of the three parts in this tripod are compatible with one another.

How can you that?

Your first resource you'll want to consult is the Compose to Kotlin Compatibility Map.

Here you can see which version of Jetpack Compose corresponds to which Kotlin version.

The second resource you will need is the releases page for the kotlin-serialization library. There you will find which library version is compatible with which Kotlin version.

Confused? 😕

Let’s illustrate this with an example:

• Your Jetpack Compose version is 1.1.0.
• Looking over the compatibility map, you see it is compatible with Kotlin version 1.6.10.
• Heading to the releases page of kotlin-serialization library, you see that the version of the kotlin-serialization library that you need to use is 1.3.2.

Head into your project level build.gradle file, and inside the buildscript object, in the dependencies section, put in classpath for the kotlin-serialization library with the version you need.

dependencies {
        ...
        classpath "org.jetbrains.kotlin:kotlin-serialization:X.Y.Z"
 }

Then, head over to your application build.gradle file and do these two things:

1. Add the id ‘org.jetbrains.kotlin.plugin.serialization’ inside of the plugins at the top of the file:

plugins {
   ...
   id 'org.jetbrains.kotlin.plugin.serialization'
}

2. At the bottom of the file, inside the dependencies section add implementation ‘org.jetbrains.kotlinx:kotlinx-serialization-json:X.Y.Z’:

dependencies {
   ...
   implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:X.Y.Z'
}

Sync your project and you should be good to go.

Note that we are using the json format of the library, but there are other formats that are supported as well:

• Protocol Buffers
• CBOR (Concise Binary Object Representation)
• Properties
• HOCON (Human Optimized Config Object Notation)

⚠️ If you encounter any errors, make sure the versions you put are correct

How to Build Your Data Class

In order to have something we can serialize and later de-serialize, we need to work with data classes.

Creating a data class is simple. If you are using Android Studio, just right click inside your project’s module and choose New Kotlin file. Enter your class name and then append the data keyword before it.

For the sake of this article, let's say we are working with an API that returns a list of users. Each user object has a range of attributes it can have (just to name a few):

• First name
• Last name
• Age
• Birthdate
• Id

To make our data class serializable, all you need to do is add the @Serializable annotation above the class declaration.

@Serializable
data class UserModel(
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

Pretty nifty, right?

Well, there’s more.

The variable that will hold the user’s first name is written as firstName. That means that in the response from our server, it needs to return in a field with the same name.

Sometimes, in API responses, the keys are not written in camelCase, but rather in kebab_case. That would mean that the key for first name, might be first_name. In that case, we would have to write it out like this:

@Serializable
data class UserModel(
   val first_name: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

But that is not the convention for property names in Kotlin.

So what can we do?

We can use the @SerialName annotation. This allows us to mark what the name of the field will be from the response and then write anything as the property for it.

@Serializable
data class UserModel(
   @SerialName("first_name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long
)

How to Serialize and De-Serialize

Now that our data class is set up, let’s enjoy the fruits of our labor. Whenever we need to serialize our data class, we will use the Json.encodeToString method:

val dataAsString: String = Json.encodeToString(user)

When we run the above line of code, we will get our data class in string form.

De-serializing our data is as simple as serializing it. We will use the Json.decodeFromString method:

val user: UserModel = Json.decodeFromString<UserModel>(dataAsString)

✋ Notice that we specified which type of data we want to de-serialize to with the type parameter ().

_Photo by [Unsplash](https://unsplash.com/@macroman?utm_source=ghost&utm_medium=referral&utm_campaign=api-credit">Immo Wegmann / <a href="https://unsplash.com/?utm_source=ghost&utm_medium=referral&utmcampaign=api-credit)

Time for some extra credit.

Let’s say that in your data class you have a field that you don’t want to serialize. If we take our UserModel class, imagine that we want to have a user’s actual picture (bitmap).

@Serializable
data class UserModel(
   @SerialName("first-name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long,
   var photo: Bitmap?
)

This is not something we will get from our API call, so how can we exclude it? Because if we don’t, our serialization will fail.

Here to our rescue is the @Transient annotation.

@Serializable
data class UserModel(
   @SerialName("first-name")
   val firstName: String,
   val lastName: String,
   val age: Int,
   val birthdate: Date,
   val id: Long,
   @Transient
   var photo: Bitmap?
)

This will exclude the marked field from being serialized and de-serialized.

• If you want to see a real life example of using serialization inside a project, you can check out a project I made here
• And if you would like to read other articles I have written, you can go here
• For more information about the kotlin-serialization library, you can go here

Thank you for reading! Happy serializing.

In the old system, we used OnClickListeners and other interfaces. In Compose, we can take full advantage of Kotlin’s Sealed Classes, Function Types and Lambda Expressions.

If you do not know what a composable is, consider reading this article which explains the fundamentals.

How to Model UI Events with a Sealed Class

First, we must learn what is meant by UI Events and how to model them with Sealed Classes.

I have described this same process for Java and Kotlin (with the old view system) before, so I will keep this brief.

The Process

For each screen or sub-screen of your UI, ask yourself this question: What are all the different ways which the user can interact with it?

Let's take an example from my first app built fully in compose, Graph Sudoku:

Screenshot of a Sudoku Android App

The sealed class I use to represent the UI interactions of this screen looks like this:

sealed class ActiveGameEvent {
    data class OnInput(val input: Int) : ActiveGameEvent()
    data class OnTileFocused(val x: Int, 
    val y: Int) : ActiveGameEvent()
    object OnNewGameClicked : ActiveGameEvent()
    object OnStart : ActiveGameEvent()
    object OnStop : ActiveGameEvent()
}

To explain briefly:

• OnInput represents a user touching an input button (like 0, 1, 2, 3, 4)

• OnTileFocused represents a user selecting a tile (like the amber highlighted one)

• OnNewGameClicked is self-explanatory

• OnStart and OnStop are lifecycle events which my composables do not care about, but they are used in the Activity which acts as a Container for the composables

Once you have your sealed class set up, you can now handle a wide variety of events using a single event handler function. Sometimes it might make more sense to have multiple event handler functions, so keep in mind that this approach must be adapted to your project's specific requirements.

How to Connect Your Software Architecture

What you have handling these events is totally up to you. Some people think that MVVM is the golden standard of software architectures, but it seems like more and more people are realizing that there is no single architecture which works best for every situation.

For Android with Compose, my current approach is to use a very 3rd party minimalist approach which typically has these things in each feature (screen):

• A (Presentation) Logic class as an event handler

• A ViewModel to store the data necessary to render the View (as the name implies)

• An Activity which acts as a Container (not a god object)

• Composables to form the View

Model-View-Whatever

I do not care what you use as long as you are applying separation of concerns. This is how I arrived at this architecture, by simply asking what should and should not be put together in the same class.

Whether you want your ViewModel, a Fragment, or an Activity to be your event handler, all of them can be set up the same way: Function Types!

Within your class of choice, set up an event handler function which accepts your sealed class as its argument:

class ActiveGameLogic(
    private val container: ActiveGameContainer?,
    private val viewModel: ActiveGameViewModel,
    private val gameRepo: IGameRepository,
    private val statsRepo: IStatisticsRepository,
    dispatcher: DispatcherProvider
) : BaseLogic<ActiveGameEvent>(dispatcher),
    CoroutineScope {
    //...
    override fun onEvent(event: ActiveGameEvent) {
        when (event) {
            is ActiveGameEvent.OnInput -> onInput(
                event.input,
                viewModel.timerState
            )
            ActiveGameEvent.OnNewGameClicked -> onNewGameClicked()
            ActiveGameEvent.OnStart -> onStart()
            ActiveGameEvent.OnStop -> onStop()
            is ActiveGameEvent.OnTileFocused -> onTileFocused(event.x, event.y)
        }
    }
    //...
}

This approach is very organized and makes it easy to test every Unit in this 3rd party library free class through a single entry point.

However, we are not done yet. Naturally, we need a way to get a reference to this event handler function, onEvent, to our Composables. We can do this using a function reference:

class ActiveGameActivity : AppCompatActivity(), ActiveGameContainer {
    private lateinit var logic: ActiveGameLogic

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val viewModel = ActiveGameViewModel()

        setContent {
            ActiveGameScreen(
                onEventHandler = logic::onEvent,
                viewModel
            )
        }

        logic = buildActiveGameLogic(this, viewModel, applicationContext)
    }

      //...
}

I am sure some of you are wondering why I am using an Activity. You can ask me during a livestream Q&A sometime for a detailed answer.

In short, Fragments appear to be a bit pointless with Compose with my approach to architecture (I do not use Jetpack Navigation), and there is nothing wrong with using Activities as a feature specific container. Just avoid writing god activities, basically.

To be specific, the way you make a reference to a function in Kotlin, is by providing the class/interface name (or skip that if it is a Top-Level function), followed by two colons, and the name of the function without any arguments or brackets:

onEventHandler = logic::onEvent

How to Replace onClickListener With Jetpack Compose onClick Modifier

With that stuff ready, we can look at how this works within the composable. Naturally, your root composable will need the event handler function as a parameter:

@Composable
fun ActiveGameScreen(
    onEventHandler: (ActiveGameEvent) -> Unit,
    viewModel: ActiveGameViewModel
) {
//...
}

It can be a bit tricky to get function type syntax correctly, but understand that this really is a reference to a function, which is not so different from a reference to a class.

Just as you should not build god objects, you should not build giant composables:

1. Break your UI down into the smallest reasonable parts

2. Wrap them in a composable function

3. For each composable which has a UI interaction associated with it, it must be given a reference to your event handler function

Here is a composable which represents the input buttons of the Sudoku app, which is given the event handler by reference:

@Composable
fun SudokuInputButton(
    onEventHandler: (ActiveGameEvent) -> Unit,
    number: Int
) {
    Button(
        onClick = { onEventHandler.invoke(ActiveGameEvent.OnInput(number)) },
        modifier = Modifier
            .requiredSize(56.dp)
            .padding(2.dp)
    ) {
        Text(
            text = number.toString(),
            style = inputButton.copy(color = MaterialTheme.colors.onPrimary),
            modifier = Modifier.fillMaxSize()
        )
    }
}

To actually pass the event to the logic class, we must use the invoke function, which will accept arguments as per the function type definition (which accepts an ActiveGameEvent in this case).

At this point, you are ready to handle UI interaction events in Kotlin (compose or not) by taking full advantage of this beautiful and modern programming language.

If you liked this article, share it on social media and consider checking out the resources below to support an independent programmer and content creator.

Social

You can find me on Instagram here and on Twitter here.

Here are some of my tutorials & courses

https://youtube.com/wiseass https://www.freecodecamp.org/news/author/ryan-michael-kay/ https://skl.sh/35IdKsj (introduction to Android with Android Studio)