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 provided a shared MutableInteractionSource, to itself and to the UI trigger simultaneously:

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, as this implementation of the Tooltip is using Compose's Popup component under the hood, it is not possible to implement such a behaviour because the tooltip popup shape must be determined by its placement, which, in the case of an automatic one, have to be determined by the position provider during its pass in calculatePosition, which, if reused to recalculate the shape inside the compose scope, might cause undesired results or errors with the framework.

TL;DR: Automatic placement is not supported.

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