Link (Standalone)
Link that stands on its own and opens a web page or another app. Compose has no link role and no Link composable, so a standalone link is a TextButton whose text names the destination; a text link's tap area is only as large as its letters.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when a control outside a paragraph opens a web page, a document, or another app (e.g., "Privacy policy", "Terms of service", "View on map").
- Use when the destination is a place the user goes to, not an action performed on the current screen.
Try a different component when
- Do not use when the link sits inside a sentence of body text (use
link.inline). - Do not use when activating it performs an action on the current screen, such as saving or deleting (use
button.basic). - Do not use when it moves between the app's top-level destinations (use
navigation-bar.basic).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- The link reports a click action and a name stating its destination. Compose has no link role, so Material's
TextButtonis the reference implementation, reportingRole.Buttonwith a 48dp target and a focus indicator; a design system's own link satisfies it by forwarding to the same semantics, and a hand-assembled one satisfies none of it by default (global.native-first). - Give the link visible text naming its destination specifically (e.g., "Privacy policy", not "Learn more" or "Click here").
- When more context is needed than the visible text carries, set
contentDescriptionon the link, opening with the visible text (e.g., "Learn more about cookies"). - Set a click label when the link leaves the app (e.g., "open in browser"), so the user knows activating it takes them out of the app.
TextButtontakes noonClickLabelparameter; set it throughModifier.semantics { onClick(label = "...", action = null) }, asbutton.basicdescribes. - Open the destination through
LocalUriHandleror anIntent, so it opens in the user's browser or the app that handles it. - Give an icon beside the link's text, such as an external-link arrow,
contentDescription = null(global.icon). - Meets the touch target baseline in
global_rules.md(global.touch-target-size). - Meets the focus states baseline in
global_rules.md(global.focus-states).
Donts
Avoid these accessibility and UX barriers.
- Do not build a standalone link from a
Textholding a singleLinkAnnotation. Its tap area is clipped to the outline of its characters, and Material draws no focus indicator for it. - Do not use
Modifier.clickableon aTextwithoutrole = Role.Button, anonClickLabel, and a 48dp minimum. It is then announced as text the user can activate, with no sign of what it does. - Do not repeat the same vague text for several links on one screen, such as three "Learn more" links. Each one needs a name that tells it apart.
- Do not use
ClickableText. It is deprecated, and is aBasicTextwith a tap detector: no link semantics, and nothing a keyboard can reach.
Customizable
Alternatives and options that give the AI agent some room to move.
- The link may be a
TextButton, or aTextwithModifier.clickable(role = Role.Button, onClickLabel = "...")andModifier.heightIn(min = 48.dp)when it must not look like a button. Both meet the same contract. - The text may be underlined, or set in the theme's primary color, to read as a link. Where it sits directly beside body text, use the underline, so it is not set apart by color alone (
global.use-of-color). - An icon may mark a link that leaves the app. The
onClickLabelcarries that meaning for TalkBack.
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun LinkExamples() {
val uriHandler = LocalUriHandler.current
Column {
TextButton(
onClick = { uriHandler.openUri("https://example.com/privacy") },
modifier = Modifier.semantics { onClick(label = "open in browser", action = null) }
) {
Text("Privacy policy")
Icon(
Icons.AutoMirrored.Filled.OpenInNew,
contentDescription = null,
modifier = Modifier.padding(start = 4.dp).size(16.dp)
)
}
TextButton(
onClick = { uriHandler.openUri("https://example.com/help/cookies") },
modifier = Modifier.semantics {
contentDescription = "Learn more about cookies"
onClick(label = "open in browser", action = null)
}
) {
Text("Learn more")
}
}
}