Scroll to text fragment

Text fragments can be used to link to a web page and highlight matching text in the URL fragment. This can be a great way to add emphasis and context to specific parts of the content you want the user to read by focusing their attention. Traditionally if you wanted to link to part of a page you would have your URL followed by the hash (#) and then the ID of that particular part. But this is not always possible, especially when linking to a website which you have no control over.

What is text fragments

The scroll to text fragment feature provides support for specifying a text snippet in the URL hash. So if I click a link that specifies a fragment, I would be navigated to that fragment of text on the page and the user agent (the browser) would emphasise it to grab my attention.

Where it’s being used

One example is Google Search . When you search for something and click on a result, Google uses text fragments to highlight the text which Google believes is the answer to your search query. The highlighted text is typically in a bright yellow highlighter colour, which is certainly noticable.

How can it be used?

The Web Platform Incubator Community Group suggest two use cases for this feature.

The first is that it could be used as a way to link to exact text references on other web pages. A good example is Wikipedia linking to the exact text for their reference links. Alternatively – as we’ve seen with Google Search – the user could be linked to the exact place where their answer may be on a web page coming from a search engine.

The second use case is for those wanting to share a particular passage of text. So you could have a feature which allows users to copy the URL for that particular part of the web page.

Browser compatibility

Currently text fragments are supported in Chromium-based browsers past version 80 , this includes Edge 83 as well as being supported in Opera 68 and Android browsers. It is not supported in Firefox and Safari and as of right now they are not intending to support this web feature .

How to use text fragments

textStart

Although it sounds really complicated, it’s actually easy to use. First let’s look at the simplest way to use text fragments.

First step is to have the URL of the page you want to link to, for example:

https://www.gov.uk/passport-fees

Next you need to add a hash (#) symbol after the URL:

https://www.gov.uk/passport-fees#

Then you need to add :~:text= :

https://www.gov.uk/passport-fees#:~:text=

Finally you need to add the textStart which is the text you want to highlight, so in our example it could be:

https://www.gov.uk/passport-fees#:~:text=Fees%20for%20returning
%20supporting%20documents

And that’s it, so now if we wanted to know the passport fees for returning supporting documents from the GOV.UK website we can directly link to the GOV.UK snippet . Remember that this only works on Chromium-based browsers at the moment.

textStart and textEnd

In the previous example we managed to link to a heading on a web page without using the ID tag. However what if we wanted to highlight the whole paragraph about fees for returning supporting documents? It wouldn’t be practical to put all of the text into the URL.

Instead what we can do is use the both the textStart and textEnd syntax to say where to start highlighting from and where to finish. In between the textStart and textEnd we just need to add a comma.

Going back to our example, what we would need to do is update our URL to look like this:

https://www.gov.uk/passport-fees#:~:text=Fees%20for%20returning%20supporting%20documents
,if%20you%20want%20to%20use%20it

What we’ve done is say that the textStart is Fees%20for%20returning%20supporting%20documents followed by a comma, and then added our textEnd which is if%20you%20want%20to%20use%20it . Our fragment example now looks like this:

prefix- and -suffix

In our examples so far it has been fairly easy to use text fragments to link to a specific part of the page. However, one of the issues with the above examples is that the URL is slowly becoming a bit long. If we wanted to, we could shorten it.

For example if we just look at the textStart parameter we could just update the URL to be:

https://www.gov.uk/passport-fees#:~:text=supporting%20documents

But then we run into a problem – there are two cases in which the words “supporting documents” are next to each other, so which one are we saying to highlight? To resolve this problem we could use the prefix- and -suffix parameters to say what word should come before or after the word(s) we’re trying to highlight.

In our case we could say that we’re looking for a prefix of “Your” before the words “supporting documents” so now our URL fragment could be:

https://www.gov.uk/passport-fees#:~:text=your-,supporting%20documents

If the word(s) at the end of your text fragment are used frequently on your page, you can use the suffix to draw attention to a specific use. For example if you wanted to highlight a particular use of the word “documents” then you could do this:

https://www.gov.uk/passport-fees#:~:text=documents,-sent%20back%20by

What is the fragment directive?

Now there is just one missing part to the puzzle. The (new) fragment directive ( :~: ).

This fragment is resevered for the user-agent (the browser) like the text= and is then removed from the URL during the loading of the web page so the author scripts cannot use it.

What’s particularly interesting about this new fragment directive is that it could be used in future features such as translation-hints or enabling an accessibility feature. By preventing the author from interacting with the fragment directive directly, it also means that these features can be implemented without it breaking exisiting content.

The full syntax

#:~:text=[prefix-,]textStart[,textEnd][,-suffix]

We’ve now covered all of the different options and ways to use text fragments. To recap, all of the values for all parameters need to be percent-encoded. This is especially important for the dash (-), ampersand (&), and comma (,) characters, so they are not being interpreted as part of the text directive syntax.

Case sensitivity

It’s also worth noting that text fragment is case insensitive , so upper and lowercase letters would be treated as the same.

Mixing traditional element links with text fragments

It’s possible to use a combination of linking to an element and then within that higlight text using the text fragment. This provides you with the benefit of, if the text changes, you are still linking to that section so the user can get close to the section of text you’re referencing or want the user to see.

Multiple text fragments

You can have multiple text fragments in an URL. You can do this by simply using an ampersand character (&) to separate the multiple fragments you want to highlight on the page. For example:

https://www.gov.uk/passport-fees#:~:text=documents&text=your-,supporting%20documents

This would highlight the first word “documents” and jump to this and as well as highlighting any words that say “supporting documents” as long as it’s after the word “your” as using the -prefix.

Browser extension

The Chrome Web Store has an extension which allows users to select and copy a link to a text fragment through the context menu. You can then send the URL to other people through email, social media and text message. As long as they open the link in a supported browser, the text fragment will be highlighted.

Further reading

• Disable Autocomplete, Autocapitalize, and Autocorrect
• How to disable text selection using CSS
• CSS url()