Tooltip (TooltipBox)

Composable wrapping a UI trigger (e.g. a button) and displaying a tooltip when the user hovers over or focuses on the UI trigger.

Tooltips display additional information upon hover or focus that is contextual, helpful, and nonessential while providing the ability to communicate and give clarity to a user.

Focus interaction

As stated by the documentation of Carbon's Tooltip component, tooltips must be triggered by a hover or focus interaction. This composable supports the hover interaction by default, as it's using BasicTooltipBox as the underlying implementation but does not support the focus interaction. However, TooltipBox supports it when a shared MutableInteractionSource is provided to both the UI trigger and itself:

val uiTriggerMutableInteractionSource = remember { MutableInteractionSource() }

TooltipBox(
    tooltipText = "To be, or not to be...",
    uiTriggerMutableInteractionSource = uiTriggerMutableInteractionSource,
) {
    MyUiTrigger(
        text = "Hover me",
        modifier = Modifier.clickable(
            interactionSource = uiTriggerMutableInteractionSource,
            indication = null,
            onClick = {}
        )
    )
}

Writing this for every UI trigger that needs the focus interaction can be cumbersome, but most common UI triggers from Carbon provides alternative APIs to ease its usage. For example, the com.gabrieldrn.carbon.button.Button composable has an alt API requiring a tooltipParameters parameter:

Button(
    label = "Hover me",
    tooltipParameters = TooltipParameters(
        text = "To be, or not to be..."
        singleLine = true,
    ),
    onClick = {}
)

Automatic placement

Carbon's documentation states that Tooltips have an automatic placement: "tooltips can detect the edges of the browser to be placed in view so the container does not get cutoff". However, this is currently not possible with the foundation elements of Compose as it would require to make multiple layout passes and sacrifice performance. As a result, it is up to consuming projects to decide the placement of tooltips.

From Tooltip documentation

Parameters

Tooltip (TooltipBox)

Convenience composable for TooltipBox that takes a TooltipParameters object as a parameter.

Composable wrapping a UI trigger (e.g. a button) and displaying a tooltip when the user hovers over or focuses on the UI trigger.

Tooltips display additional information upon hover or focus that is contextual, helpful, and nonessential while providing the ability to communicate and give clarity to a user.

From Tooltip documentation

Parameters