도움말을 사용하여 버튼이나 기타 UI 요소에 컨텍스트를 추가합니다.
도움말에는 두 가지 유형이 있습니다.
일반 도움말: 아이콘 버튼의 요소 또는 작업을 설명합니다.
리치 도움말: 기능의 값을 설명하는 등 자세한 정보를 제공합니다. 선택사항인 제목, 링크, 버튼을 포함할 수도 있습니다.
그림 1. 일반 도움말 (1)과 리치 도움말 (2)
API 노출 영역
TooltipBox 컴포저블을 사용하여 앱에서 도움말을 구현할 수 있습니다.
다음 기본 매개변수를 사용하여 TooltipBox 모양을 제어합니다.
positionProvider: 앵커 콘텐츠를 기준으로 툴팁을 배치합니다. 일반적으로 TooltipDefaults의 기본 위치 제공자를 사용하지만 맞춤 위치 지정 로직이 필요한 경우 자체 위치 제공자를 제공할 수 있습니다.
tooltip: 도움말의 콘텐츠를 포함하는 컴포저블입니다. 일반적으로 PlainTooltip 또는 RichTooltip 컴포저블을 사용합니다.
PlainTooltip을 사용하여 아이콘 버튼의 요소나 작업을 설명합니다.
RichTooltip를 사용하여 기능의 가치를 설명하는 등 자세한 내용을 제공하세요. 리치 도움말에는 선택적 제목, 링크, 버튼이 포함될 수 있습니다.
state: 이 도움말의 UI 로직과 요소 상태를 포함하는 상태 홀더입니다.
content: 툴팁이 고정된 컴포저블 콘텐츠입니다.
일반 도움말 표시
일반 툴팁을 사용하여 UI 요소를 간략하게 설명합니다. 이 코드 스니펫은 '즐겨찾기에 추가' 라벨이 지정된 아이콘 버튼 위에 일반 툴팁을 표시합니다.
@ComposablefunPlainTooltipExample(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")}}}
TooltipBox은 사용자 상호작용의 이벤트 리스너를 처리하고 이에 따라 TooltipState을 업데이트합니다. TooltipState가 도움말을 표시해야 함을 나타내면 도움말 람다가 실행되고 TooltipBox이 RichTooltip를 표시합니다. TooltipBox는 콘텐츠와 도움말의 앵커 및 컨테이너 역할을 합니다.
이 경우 콘텐츠는 탭할 수 있는 작업 동작을 제공하는 IconButton 구성요소입니다. TooltipBox의 콘텐츠에서 아무 곳이나 길게 누르거나(터치 기기) 마우스 포인터로 가져가면 도움말이 표시되어 자세한 정보를 보여줍니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-08-27(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-27(UTC)"],[],[],null,["Use [tooltips](https://m3.material.io/components/tooltips/overview) to add context to a button or other UI element.\nThere are two types of tooltips:\n\n- **Plain tooltips**: Describe elements or actions of icon buttons.\n- **Rich tooltips**: Provide more detail, such as describing the value of a feature. Can also include an optional title, link, and buttons.\n\n**Figure 1.** A plain tooltip (1) and a rich tooltip (2).\n\nAPI surface\n\nYou can use the [`TooltipBox`](/reference/kotlin/androidx/compose/material3/package-summary#TooltipBox(androidx.compose.ui.window.PopupPositionProvider,kotlin.Function1,androidx.compose.material3.TooltipState,androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Boolean,kotlin.Boolean,kotlin.Function0)) composable to implement tooltips in your app.\nYou control [`TooltipBox`](/reference/kotlin/androidx/compose/material3/package-summary#TooltipBox(androidx.compose.ui.window.PopupPositionProvider,kotlin.Function1,androidx.compose.material3.TooltipState,androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Boolean,kotlin.Boolean,kotlin.Function0)) appearance with these main parameters:\n\n- `positionProvider`: Places the tooltip relative to the anchor content. You typically use a default position provider from the `TooltipDefaults`, or you can provide your own if you need custom positioning logic.\n- `tooltip`: The composable that contains the tooltip's content. You typically use either the `PlainTooltip` or `RichTooltip` composables.\n - Use `PlainTooltip` to describe elements or actions of icon buttons.\n - Use `RichTooltip` to provide more details, like describing the value of a feature. Rich tooltips can include an optional title, link, and buttons.\n- `state`: The state holder that contains the UI logic and element state for this tooltip.\n- `content`: The composable content that the tooltip is anchored to.\n\nDisplay a plain tooltip\n\nUse a plain tooltip to briefly describe a UI element. This code snippet displays\na plain tooltip on top of an icon button, labeled \"Add to favorites\":\n\n\n```kotlin\n@Composable\nfun PlainTooltipExample(\n modifier: Modifier = Modifier,\n plainTooltipText: String = \"Add to favorites\"\n) {\n TooltipBox(\n modifier = modifier,\n positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),\n tooltip = {\n PlainTooltip { Text(plainTooltipText) }\n },\n state = rememberTooltipState()\n ) {\n IconButton(onClick = { /* Do something... */ }) {\n Icon(\n imageVector = Icons.Filled.Favorite,\n contentDescription = \"Add to favorites\"\n )\n }\n }\n}\nhttps://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Tooltips.kt#L74-L95\n```\n\n\u003cbr /\u003e\n\nKey points about the code\n\n- `TooltipBox` generates a tooltip with the text \"Add to favorites\".\n - [`TooltipDefaults.rememberPlainTooltipPositionProvider()`](/reference/kotlin/androidx/compose/material3/TooltipDefaults?#rememberPlainTooltipPositionProvider(androidx.compose.ui.unit.Dp)) provides default positioning for plain tooltips.\n - `tooltip` is a lambda function that defines the tooltip's content using the [`PlainTooltip`](/reference/kotlin/androidx/compose/material3/TooltipScope#(androidx.compose.material3.TooltipScope).PlainTooltip(androidx.compose.ui.Modifier,androidx.compose.ui.unit.DpSize,androidx.compose.ui.unit.Dp,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.unit.Dp,kotlin.Function0)) composable.\n - `Text(plainTooltipText)` displays the text within the tooltip.\n - [`tooltipState`](/reference/kotlin/androidx/compose/material3/TooltipState) controls the state of the tooltip.\n- `IconButton` creates a clickable button with an icon.\n - `Icon(...)` displays a heart icon within the button.\n - When a user interacts with the `IconButton`, `TooltipBox` shows the tooltip with the text \"Add to favorites\". Depending on the device, users can trigger the tooltip in the following ways:\n - Hovering over the icon with a cursor\n - Long-pressing the icon on a mobile device\n\nResult\n\nThis example produces a plain tooltip on top of an icon:\n**Figure 2.**A plain tooltip that appears when a user hovers over or long-presses the heart icon.\n\nDisplay a rich tooltip\n\nUse a rich tooltip to provide additional context about a UI element. This\nexample creates a multi-line rich tooltip with a title that is anchored to an\n`Icon`:\n\n\n```kotlin\n@Composable\nfun RichTooltipExample(\n modifier: Modifier = Modifier,\n richTooltipSubheadText: String = \"Rich Tooltip\",\n richTooltipText: String = \"Rich tooltips support multiple lines of informational text.\"\n) {\n TooltipBox(\n modifier = modifier,\n positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),\n tooltip = {\n RichTooltip(\n title = { Text(richTooltipSubheadText) }\n ) {\n Text(richTooltipText)\n }\n },\n state = rememberTooltipState()\n ) {\n IconButton(onClick = { /* Icon button's click event */ }) {\n Icon(\n imageVector = Icons.Filled.Info,\n contentDescription = \"Show more information\"\n )\n }\n }\n}https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Tooltips.kt#L106-L131\n```\n\n\u003cbr /\u003e\n\nKey points about the code\n\n- `TooltipBox` handles the event listeners for user interactions and updates `TooltipState` accordingly. When `TooltipState` indicates that the tooltip should be shown, the tooltip lambda executes, and `TooltipBox` displays the `RichTooltip`. The `TooltipBox` acts as the anchor and container for both content and the tooltip.\n - In this case, the content is an `IconButton` component, which provides the tappable action behavior. When long-pressed (on touch devices) or hovered over (as with the mouse pointer) anywhere in `TooltipBox`'s content, the tooltip will display to show more information.\n- The `RichTooltip` composable defines the tooltip's content, including the title and body text. [`TooltipDefaults.rememberRichTooltipPositionProvider()`](/reference/kotlin/androidx/compose/material3/TooltipDefaults?#rememberRichTooltipPositionProvider(androidx.compose.ui.unit.Dp)) provides positioning information for rich tooltips.\n\nResult\n\nThis example produces a rich tooltip with a title attached to an information\nicon:\n**Figure 3.**A rich tooltip with a title and an information icon.\n\nCustomize a rich tooltip\n\nThis code snippet displays a rich tooltip with a title, custom actions, and a\ncustom caret (arrow) displayed on top of a camera icon button:\n\n\n```kotlin\n@Composable\nfun AdvancedRichTooltipExample(\n modifier: Modifier = Modifier,\n richTooltipSubheadText: String = \"Custom Rich Tooltip\",\n richTooltipText: String = \"Rich tooltips support multiple lines of informational text.\",\n richTooltipActionText: String = \"Dismiss\"\n) {\n val tooltipState = rememberTooltipState()\n val coroutineScope = rememberCoroutineScope()\n\n TooltipBox(\n modifier = modifier,\n positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),\n tooltip = {\n RichTooltip(\n title = { Text(richTooltipSubheadText) },\n action = {\n Row {\n TextButton(onClick = {\n coroutineScope.launch {\n tooltipState.dismiss()\n }\n }) {\n Text(richTooltipActionText)\n }\n }\n },\n caretSize = DpSize(32.dp, 16.dp)\n ) {\n Text(richTooltipText)\n }\n },\n state = tooltipState\n ) {\n IconButton(onClick = {\n coroutineScope.launch {\n tooltipState.show()\n }\n }) {\n Icon(\n imageVector = Icons.Filled.Camera,\n contentDescription = \"Open camera\"\n )\n }\n }\n}https://github.com/android/snippets/blob/dd30aee903e8c247786c064faab1a9ca8d10b46e/compose/snippets/src/main/java/com/example/compose/snippets/components/Tooltips.kt#L142-L187\n```\n\n\u003cbr /\u003e\n\nKey points about the code\n\n- A `RichToolTip` displays a tooltip with a title and dismiss action.\n- When activated, either by a long-press or hovering over the `ToolTipBox` content with the mouse pointer, the tooltip is displayed for about one second. You can dismiss this tooltip by either tapping elsewhere on the screen or using the dismiss action button.\n- When the dismiss action executes, the system launches a coroutine to call `tooltipState.dismiss`. This verifies the action execution isn't blocked while the tooltip is displayed.\n- `onClick = coroutineScope.launch { tooltipState.show() } }` launches a coroutine to manually show the tooltip using `tooltipState.show`.\n- The `action` parameter allows for the adding of interactive elements to a tooltip, such as a button.\n- The `caretSize` parameter modifies the size of the tooltip's arrow.\n\nResult\n\nThis example produces the following:\n**Figure 4.** A custom rich tooltip with a dismiss action anchored to a camera icon.\n\nAdditional resources\n\n- Material Design: [Tooltips](https://m3.material.io/components/tooltips/overview)"]]