{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

TooltipKt

public final class TooltipKt


Summary

Public methods

static final void
@Composable
@ExperimentalMaterial3Api
PlainTooltip(
    @NonNull CaretScope receiver,
    @NonNull Modifier modifier,
    CaretProperties caretProperties,
    @NonNull Shape shape,
    @NonNull Color contentColor,
    @NonNull Color containerColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @Composable @NonNull Function0<Unit> content
)

Plain tooltip that provides a descriptive message.

static final void
@Composable
@ExperimentalMaterial3Api
RichTooltip(
    @NonNull Modifier modifier,
    @Composable Function0<Unit> title,
    @Composable Function0<Unit> action,
    @NonNull Shape shape,
    @NonNull RichTooltipColors colors,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @Composable @NonNull Function0<Unit> text
)

Rich text tooltip that allows the user to pass in a title, text, and action.

static final void
@Composable
@ExperimentalMaterial3Api
TooltipBox(
    @NonNull PopupPositionProvider positionProvider,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull CaretScopeUnit> tooltip,
    @NonNull TooltipState state,
    @NonNull Modifier modifier,
    boolean focusable,
    boolean enableUserInput,
    @Composable @NonNull Function0<Unit> content
)

Material TooltipBox that wraps a composable with a tooltip.

static final @NonNull TooltipState
@ExperimentalMaterial3Api
TooltipState(
    boolean initialIsVisible,
    boolean isPersistent,
    @NonNull MutatorMutex mutatorMutex
)

Constructor extension function for TooltipState

static final @NonNull TooltipState
@Composable
@ExperimentalMaterial3Api
rememberTooltipState(
    boolean initialIsVisible,
    boolean isPersistent,
    @NonNull MutatorMutex mutatorMutex
)

Create and remember the default TooltipState for TooltipBox.

Public methods

PlainTooltip

@Composable
@ExperimentalMaterial3Api
public static final void PlainTooltip(
    @NonNull CaretScope receiver,
    @NonNull Modifier modifier,
    CaretProperties caretProperties,
    @NonNull Shape shape,
    @NonNull Color contentColor,
    @NonNull Color containerColor,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @Composable @NonNull Function0<Unit> content
)

Plain tooltip that provides a descriptive message.

Usually used with TooltipBox.

Parameters
@NonNull Modifier modifier

the Modifier to be applied to the tooltip.

CaretProperties caretProperties

CaretProperties for the caret of the tooltip, if a default caret is desired with a specific dimension. Please see TooltipDefaults.caretProperties to see the default dimensions. Pass in null for this parameter if no caret is desired.

@NonNull Shape shape

the Shape that should be applied to the tooltip container.

@NonNull Color contentColor

Color that will be applied to the tooltip's content.

@NonNull Color containerColor

Color that will be applied to the tooltip's container.

@NonNull Dp tonalElevation

the tonal elevation of the tooltip.

@NonNull Dp shadowElevation

the shadow elevation of the tooltip.

@Composable @NonNull Function0<Unit> content

the composable that will be used to populate the tooltip's content.

RichTooltip

@Composable
@ExperimentalMaterial3Api
public static final void RichTooltip(
    @NonNull Modifier modifier,
    @Composable Function0<Unit> title,
    @Composable Function0<Unit> action,
    @NonNull Shape shape,
    @NonNull RichTooltipColors colors,
    @NonNull Dp tonalElevation,
    @NonNull Dp shadowElevation,
    @Composable @NonNull Function0<Unit> text
)

Rich text tooltip that allows the user to pass in a title, text, and action. Tooltips are used to provide a descriptive message.

Usually used with TooltipBox

Parameters
@NonNull Modifier modifier

the Modifier to be applied to the tooltip.

@Composable Function0<Unit> title

An optional title for the tooltip.

@Composable Function0<Unit> action

An optional action for the tooltip.

@NonNull Shape shape

the Shape that should be applied to the tooltip container.

@NonNull RichTooltipColors colors

RichTooltipColors that will be applied to the tooltip's container and content.

@NonNull Dp tonalElevation

the tonal elevation of the tooltip.

@NonNull Dp shadowElevation

the shadow elevation of the tooltip.

@Composable @NonNull Function0<Unit> text

the composable that will be used to populate the rich tooltip's text.

TooltipBox

@Composable
@ExperimentalMaterial3Api
public static final void TooltipBox(
    @NonNull PopupPositionProvider positionProvider,
    @Composable @ExtensionFunctionType @NonNull Function1<@NonNull CaretScopeUnit> tooltip,
    @NonNull TooltipState state,
    @NonNull Modifier modifier,
    boolean focusable,
    boolean enableUserInput,
    @Composable @NonNull Function0<Unit> content
)

Material TooltipBox that wraps a composable with a tooltip.

tooltips provide a descriptive message for an anchor. It can be used to call the users attention to the anchor.

Tooltip that is invoked when the anchor is long pressed:

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
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

TooltipBox(
    positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
    tooltip = {
        PlainTooltip {
            Text("Add to favorites")
        }
    },
    state = rememberTooltipState()
) {
    IconButton(
        onClick = { /* Icon button's click event */ }
    ) {
        Icon(
            imageVector = Icons.Filled.Favorite,
            contentDescription = "Localized Description"
        )
    }
}

If control of when the tooltip is shown is desired please see

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.AddCircle
import androidx.compose.material3.Icon
import androidx.compose.material3.OutlinedButton
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.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

val tooltipState = rememberTooltipState()
val scope = rememberCoroutineScope()
Column(
    horizontalAlignment = Alignment.CenterHorizontally
) {
    TooltipBox(
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip {
                Text("Add to list")
            }
        },
        state = tooltipState
    ) {
        Icon(
            imageVector = Icons.Filled.AddCircle,
            contentDescription = "Localized Description"
        )
    }
    Spacer(Modifier.requiredHeight(30.dp))
    OutlinedButton(
        onClick = { scope.launch { tooltipState.show() } }
    ) {
        Text("Display tooltip")
    }
}

Plain tooltip with caret shown on long press:

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
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

TooltipBox(
    positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
    tooltip = {
        PlainTooltip(
            caretProperties = TooltipDefaults.caretProperties
        ) {
            Text("Add to favorites")
        }
    },
    state = rememberTooltipState()
) {
    IconButton(
        onClick = { /* Icon button's click event */ }
    ) {
        Icon(
            imageVector = Icons.Filled.Favorite,
            contentDescription = "Localized Description"
        )
    }
}

Tooltip that is invoked when the anchor is long pressed:

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Info
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.rememberCoroutineScope

val tooltipState = rememberTooltipState(isPersistent = true)
val scope = rememberCoroutineScope()
TooltipBox(
    positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
    tooltip = {
        RichTooltip(
            title = { Text(richTooltipSubheadText) },
            action = {
                TextButton(
                    onClick = { scope.launch { tooltipState.dismiss() } }
                ) { Text(richTooltipActionText) }
            }
        ) {
            Text(richTooltipText)
        }
    },
    state = tooltipState
) {
    IconButton(
        onClick = { /* Icon button's click event */ }
    ) {
        Icon(
            imageVector = Icons.Filled.Info,
            contentDescription = "Localized Description"
        )
    }
}

If control of when the tooltip is shown is desired please see

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Info
import androidx.compose.material3.Icon
import androidx.compose.material3.OutlinedButton
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.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

val tooltipState = rememberTooltipState(isPersistent = true)
val scope = rememberCoroutineScope()
Column(
    horizontalAlignment = Alignment.CenterHorizontally
) {
    TooltipBox(
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    TextButton(
                        onClick = {
                            scope.launch {
                                tooltipState.dismiss()
                            }
                        }
                    ) { Text(richTooltipActionText) }
                }
            ) { Text(richTooltipText) }
        },
        state = tooltipState
    ) {
        Icon(
            imageVector = Icons.Filled.Info,
            contentDescription = "Localized Description"
        )
    }
    Spacer(Modifier.requiredHeight(30.dp))
    OutlinedButton(
        onClick = { scope.launch { tooltipState.show() } }
    ) {
        Text("Display tooltip")
    }
}
Parameters
@NonNull PopupPositionProvider positionProvider

PopupPositionProvider that will be used to place the tooltip relative to the anchor content.

@Composable @ExtensionFunctionType @NonNull Function1<@NonNull CaretScopeUnit> tooltip

the composable that will be used to populate the tooltip's content.

@NonNull TooltipState state

handles the state of the tooltip's visibility.

@NonNull Modifier modifier

the Modifier to be applied to the TooltipBox.

boolean focusable

Boolean that determines if the tooltip is focusable. When true, the tooltip will consume touch events while it's shown and will have accessibility focus move to the first element of the component. When false, the tooltip won't consume touch events while it's shown but assistive-tech users will need to swipe or drag to get to the first element of the component.

boolean enableUserInput

Boolean which determines if this TooltipBox will handle long press and mouse hover to trigger the tooltip through the state provided.

@Composable @NonNull Function0<Unit> content

the composable that the tooltip will anchor to.

TooltipState

@ExperimentalMaterial3Api
public static final @NonNull TooltipState TooltipState(
    boolean initialIsVisible,
    boolean isPersistent,
    @NonNull MutatorMutex mutatorMutex
)

Constructor extension function for TooltipState

Parameters
boolean initialIsVisible

the initial value for the tooltip's visibility when drawn.

boolean isPersistent

Boolean that determines if the tooltip associated with this will be persistent or not. If isPersistent is true, then the tooltip will only be dismissed when the user clicks outside the bounds of the tooltip or if TooltipState.dismiss is called. When isPersistent is false, the tooltip will dismiss after a short duration. Ideally, this should be set to true when there is actionable content being displayed within a tooltip.

@NonNull MutatorMutex mutatorMutex

MutatorMutex used to ensure that for all of the tooltips associated with the mutator mutex, only one will be shown on the screen at any time.

rememberTooltipState

@Composable
@ExperimentalMaterial3Api
public static final @NonNull TooltipState rememberTooltipState(
    boolean initialIsVisible,
    boolean isPersistent,
    @NonNull MutatorMutex mutatorMutex
)

Create and remember the default TooltipState for TooltipBox.

Parameters
boolean initialIsVisible

the initial value for the tooltip's visibility when drawn.

boolean isPersistent

Boolean that determines if the tooltip associated with this will be persistent or not. If isPersistent is true, then the tooltip will only be dismissed when the user clicks outside the bounds of the tooltip or if TooltipState.dismiss is called. When isPersistent is false, the tooltip will dismiss after a short duration. Ideally, this should be set to true when there is actionable content being displayed within a tooltip.

@NonNull MutatorMutex mutatorMutex

MutatorMutex used to ensure that for all of the tooltips associated with the mutator mutex, only one will be shown on the screen at any time.