Link (Inline)
Link inside a sentence of body text, built with LinkAnnotation. TalkBack reaches it through its Links menu rather than as a stop of its own, and Material draws nothing when a keyboard focuses it, so the link's text and its focused style are the caller's to get right.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when a link sits inside a sentence or paragraph of body text (e.g., "By continuing, you agree to the terms of service and privacy policy.").
- Use when the linked words are part of the sentence and pulling them out would break it.
Try a different component when
- Do not use when the link stands on its own outside body text (use
link.basic). - Do not use when activating it performs an action on the current screen rather than opening something (use
button.basic).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- Each link is exposed to accessibility services as a link inside its text and is reachable from a keyboard.
LinkAnnotation.UrlandLinkAnnotation.Clickable, built withwithLinkin abuildAnnotatedStringand rendered in Material'sText, are the reference implementation: Compose publishes each one as aURLSpanorClickableSpanand makes it focusable (global.native-first). - Use
LinkAnnotation.Urlfor a web address, andLinkAnnotation.Clickablewith alinkInteractionListenerfor an action inside the app. - Give each link text that names its destination on its own (e.g., "privacy policy", not "here" or "this page"). TalkBack's Links menu lists the links by their text alone.
- Set a
focusedStylein the link'sTextLinkStylesthat differs from the resting style by more than the text's color, such as a background highlight behind the linked words. Material's default link style sets no focused state, and the link draws no focus indicator of its own (global.focus-states). - Keep an underline on the link's resting style. Material's
Textapplies one by default; customTextLinkStylesreplace it, so they have to carry their own (global.use-of-color). - Draw the link's color from the theme's color scheme, so it keeps its contrast against the text and background in light and dark themes (
global.semantic-color).
Donts
Avoid these accessibility and UX barriers.
- Do not put a paragraph with inline links inside a clickable row or card. The links are a second set of targets inside a control that already merges its content (
global.merge-semantics). - Do not use
ClickableText. It is deprecated, and is aBasicTextwith a tap detector: no link semantics, and nothing a keyboard can reach. - Do not set
TextLinkStyleswith a color change alone. The link then differs from the surrounding text only by hue. - Do not render inline links with
BasicTextand noTextLinkStyles.BasicTextapplies no link style, so the link looks like the rest of the sentence. - Do not make a link carry a whole paragraph's meaning. TalkBack users meet it in the Links menu without the sentence.
Customizable
Alternatives and options that give the AI agent some room to move.
- A paragraph may hold several links. Each is its own entry in the Links menu and its own keyboard stop.
- The
focusedStylemay be a background color, a heavier underline, or both, provided it is visible against both the resting link and the text around it. hoveredStyleandpressedStylemay also be set for pointer and touch feedback; they do not replacefocusedStyle.- The tap area of an inline link is the linked text itself, which is expected inside a sentence. A link that must be easy to hit belongs outside the paragraph, in
link.basic.
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun InlineLinkExamples(onOpenSettings: () -> Unit) {
val linkStyles = TextLinkStyles(
style = SpanStyle(
color = MaterialTheme.colorScheme.primary,
textDecoration = TextDecoration.Underline
),
focusedStyle = SpanStyle(
background = MaterialTheme.colorScheme.primaryContainer,
textDecoration = TextDecoration.Underline
)
)
Text(
buildAnnotatedString {
append("By continuing, you agree to the ")
withLink(LinkAnnotation.Url("https://example.com/terms", linkStyles)) {
append("terms of service")
}
append(" and ")
withLink(LinkAnnotation.Url("https://example.com/privacy", linkStyles)) {
append("privacy policy")
}
append(". You can change this in ")
withLink(
LinkAnnotation.Clickable(
tag = "settings",
styles = linkStyles,
linkInteractionListener = { onOpenSettings() }
)
) {
append("privacy settings")
}
append(".")
}
)
}