2. Operable · 2.4 Navigable

2.4.4 — Link Purpose (In Context)

Level A

Engineering guidance on this page is adapted from Appt.org (Appt Foundation), used under the CC BY-SA 4.0 license. In keeping with that license, the adapted content on this page is likewise available under CC BY-SA 4.0. "Appt" is a registered trademark of the Appt Foundation; this page is not affiliated with or endorsed by Appt.

Mark links

On Android, links should be embedded inside an URLSpan.

To create text links, you can show the span in using the setText) method of TextView. To support assistive technologies on lower version of Android, you need to call the ViewCompat.enableAccessibleClickableSpanSupport()) method.

The helper method ViewCompat.addLinks()) is also useful to automatically create accessible links.

Warning: you have to remove the android:autoLink attribute from your XML to make your URLSpan's clickable.

kotlin

val textView = TextView(this)

val url = "https://appt.org"
val link = "Appt"

val spannableString = SpannableString("Learn more about $link")

val index = spannableString.indexOf(link)
spannableString.setSpan(URLSpan(url), index, index + link.length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)

textView.text = spannableString
textView.movementMethod = LinkMovementMethod.getInstance()

ViewCompat.enableAccessibleClickableSpanSupport(textView)

In Jetpack Compose, starting from compose-ui 1.7.0 you can use LinkAnnotation.Url of AnnotatedString to add an inline link to the text.

Clicking on the link will automatically open it in the default browser.

kotlin

val textWithLink = buildAnnotatedString {
    append("Learn more about ")
    // adding clickable url
    withLink(
        LinkAnnotation.Url(
            url = "https://appt.org",
            // adding style for the url
            styles = TextLinkStyles(
                style = SpanStyle(textDecoration = TextDecoration.Underline, color = Color.Blue)
            )
        )
    ) {
        append("Appt")
    }
}
Text(textWithLink)

On iOS, links should contain the link attribute. This attribute can be added through the addAttribute method of NSMutableAttributedString

To create text links, you can show the attributed string by using the the attributedText property of UILabel.

Depending on how your links are created, you might need to set the .link trait as accessibilityTraits.

swift

guard let url = URL(string: "https://appt.org") else { return }
let link = "Appt"

let attributedString = NSMutableAttributedString(string: "Learn more about \(link)")

let range = attributedString.mutableString.range(of: link)
attributedString.addAttribute(.link, value: url, range: range)

let label = UILabel()
label.attributedText = attributedString

// Optional: add .link accessibility trait to whole label
label.accessibilityTraits = .link

In SwiftUI, you can create rich text that includes clickable links using the AttributedString and its link attribute. This approach allows you to make specific parts of your text act as hyperlinks.

swift

let attributedTextLink: AttributedString = {
    var fullText = AttributedString("Learn more about Appt")
    
    // Find the range of the word "Appt"
    if let range = fullText.range(of: "Appt") {
        // Add link attribute to "Appt"
        fullText[range].link = URL(string: "https://appt.org/en/")!
    }
    
    return fullText
}()

Text(attributedTextLink)

swift

Link("Visit Appt", destination: URL(string: "https://appt.org")!)

In Flutter, links should have the semantic property link.

To create text links, you can use the RichText widget. You can pass multiple TextSpan widgets as it's children.

The url_launcher package can be used to open links.

dart

RichText(
    text: TextSpan(
      children: [
        TextSpan(text: "Learn more about "),
        WidgetSpan(
            child: Semantics(
              link: true,
              hint: "External link",
              child: GestureDetector(
                onTap: () => launchUrl(Uri.parse("https://appt.org")),
                child: Text(
                  "Appt",
                  style: TextStyle(
                    decoration: TextDecoration.underline,
                    color: Theme.of(context).colorScheme.primary,
                    decorationColor: Theme.of(context).colorScheme.primary,
                  ),
                ),
              )
            )
        ),
      ]
    )
);

In React Native, links should have their accessibilityRole set to link. You can use accessibilityLabel or accessibilityHint to provide additional context.

To create text links, you can embed a Text component inside a Pressable component.

The Linking API can be used to open links.

jsx

<Pressable
  onPress={async () => {
    const supported = await Linking.canOpenURL(url);
    if (supported) {
      await Linking.openURL(url);
    }
  }}
  accessibilityRole="link"
  accessibilityLabel="Appt"
  accessibilityHint="External link"
>
  <Text>Appt</Text>
</Pressable>

In MAUI, there is no built-in support to indicate content as a link.

Generally, it is more important to help users understand what will happen when they perform an action on the accessibility element. In this case, an accessibility hint could be used.

csharp

Not available, contribute!

In Xamarin, you need to follow four steps to create links:

Set the TextColor and TextDecoration properties of the Label or Span.
Add a TapGestureRecognizer to the GestureRecognizers collection of the Label or Span, whose Command property binds to a ICommand, and whose CommandParameter property contains the URL to open.
Define the ICommand that will be executed by the TapGestureRecognizer.
Write the code that will be executed by the ICommand.

For more information, see Xamarin Hyperlinks, it includes information how you can create your own Hyperlink class.

xml

<Label>
    <Label.FormattedText>
        <FormattedString>
            <Span Text="Read more about " />
            <Span Text="Appt"
                  TextColor="Blue"
                  TextDecorations="Underline">
                <Span.GestureRecognizers>
                    <TapGestureRecognizer Command="{Binding TapCommand}"
                                          CommandParameter="https://appt.org" />
                </Span.GestureRecognizers>
            </Span>
        </FormattedString>
    </Label.FormattedText>
</Label>

← Back to Engineering Support

2.4.4 — Link Purpose (In Context)

Mark links

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

.NET MAUI

Xamarin