How to Use Tooltip Components in Jetpack Compose (With Usage Examples)

Overview

Tooltips in Jetpack Compose provide contextual information for UI elements like buttons. They come in two types: PlainTooltip for brief descriptions of icon buttons and RichTooltip for detailed information, optionally including titles, links, or buttons.

This guide demonstrates how to implement Plain, Rich, and Custom Rich Tooltips with customization options and best practices.

When to Use Tooltips

Tooltip Type	When to Use
Plain Tooltip	Briefly describe icon buttons or simple UI elements, like "Add to favorites" for a heart icon.
Rich Tooltip	Provide detailed context for features, such as explaining a button's functionality with multi-line text.
Custom Rich Tooltip	Offer interactive or branded tooltips, like adding dismiss buttons or custom styling for settings or camera actions.

Creating Tooltip Components in Jetpack Compose

Plain Tooltip Example

Creates a simple tooltip to describe an icon button, such as a favorites button.


import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.PlainTooltip
import androidx.compose.material3.Text
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}

Result: A plain tooltip appears above the heart icon when hovered or long-pressed, displaying "Add to favorites".

Scenario: Use to provide concise descriptions for icon buttons, such as labeling a heart icon as a favorites toggle in a media app.

A plain tooltip that appears when a user hovers over or long-presses the heart icon.

Plain Tooltip Properties

Property	Description
positionProvider	Sets tooltip placement (e.g., `TooltipDefaults.rememberPlainTooltipPositionProvider()`).
tooltip	Defines tooltip content using `PlainTooltip` (e.g., `Text("Add to favorites")`).
state	Manages tooltip state with `rememberTooltipState()`.
content	Anchors the tooltip to a composable, like `IconButton`.

Rich Tooltip Example

Creates a multi-line tooltip with a title to explain a feature, such as an info button.


import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.RichTooltip
import androidx.compose.material3.Text
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Info

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}

Result: A rich tooltip with a title and multi-line text appears above the info icon when hovered or long-pressed.

Scenario: Use to provide detailed explanations for UI elements, such as describing the functionality of an info button in a settings screen.

A rich tooltip with a title and an information icon.

Rich Tooltip Properties

Property	Description
positionProvider	Sets tooltip placement (e.g., `TooltipDefaults.rememberRichTooltipPositionProvider()`).
tooltip	Defines tooltip content using `RichTooltip` with title and text.
state	Manages tooltip state with `rememberTooltipState()`.
content	Anchors the tooltip to a composable, like `IconButton`.
title	Sets the tooltip title (e.g., `Text("Rich Tooltip")`).

Custom Rich Tooltip Example

Creates a rich tooltip with a dismiss action and custom caret for branded or interactive scenarios, like a camera button.


import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.RichTooltip
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Camera
import kotlinx.coroutines.launch

@Composable
fun CustomRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}

Result: A rich tooltip with a title, dismiss button, and custom caret appears above the camera icon when clicked, hovered, or long-pressed.

Scenario: Use for interactive or branded tooltips, such as explaining camera functionality with a dismiss option in a photography app.

A custom rich tooltip with a dismiss action anchored to a camera icon.

Custom Rich Tooltip Properties

Property	Description
positionProvider	Sets tooltip placement (e.g., `TooltipDefaults.rememberRichTooltipPositionProvider()`).
tooltip	Defines tooltip content using `RichTooltip` with title, text, and action.
state	Manages tooltip state with `rememberTooltipState()`.
content	Anchors the tooltip to a composable, like `IconButton`.
title	Sets the tooltip title (e.g., `Text("Custom Rich Tooltip")`).
action	Adds interactive elements, like a `TextButton` for dismissing.
caretSize	Sets the size of the tooltip’s arrow (e.g., `DpSize(32.dp, 16.dp)`).

Key Points for Implementation

positionProvider: Defines tooltip placement using TooltipDefaults or custom logic.
tooltip: Specifies content with PlainTooltip or RichTooltip for simple or detailed descriptions.
state: Manages visibility with rememberTooltipState(), supporting show/dismiss actions.
content: Anchors the tooltip to a composable, like IconButton.
title/action/caretSize: Customize RichTooltip with a title, interactive buttons, or arrow size.
Accessibility: Ensure tooltips provide contentDescription for anchored elements and are triggered by hover or long-press for screen reader compatibility.

Theming Tooltips

Customize Tooltip appearance using MaterialTheme in Compose to define colors or apply specific styles via RichTooltip parameters.


import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.PlainTooltip
import androidx.compose.material3.Text
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.rememberTooltipState
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite

@Composable
fun ThemedTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    MaterialTheme(
        colorScheme = MaterialTheme.colorScheme.copy(
            primary = Color(0xFF1767d0)
        )
    ) {
        TooltipBox(
            modifier = modifier,
            positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
            tooltip = {
                PlainTooltip { Text(plainTooltipText) }
            },
            state = rememberTooltipState()
        ) {
            IconButton(onClick = { /* Do something... */ }) {
                Icon(
                    imageVector = Icons.Filled.Favorite,
                    contentDescription = "Add to favorites"
                )
            }
        }
    }
}

Additional Resources

Material Design: Tooltips

FAQ

What is a Tooltip component?

A contextual popup providing brief or detailed information about a UI element, triggered by hover or long-press.

Which composable is used for Tooltips?

Use TooltipBox with PlainTooltip or RichTooltip for content.

How to make Tooltips accessible?

Ensure anchored elements have contentDescription and support hover/long-press triggers for screen readers.

Can I customize Tooltip appearance?

Yes, via positionProvider, title, action, caretSize, or MaterialTheme.colorScheme.

How to Use Tooltip Components in Jetpack Compose?