Last updated:
6 hours ago
Text fragments enable users to link directly to a specific portion of text within a web document without requiring the document’s author to annotate the text with an ID. This feature leverages a unique syntax in the URL fragment to identify and highlight the target text.
This enables you to create links that highlight a specific portion of text on a webpage. When someone clicks your link, the browser navigates to the webpage and automatically scrolls to and highlights the desired text.
How to use text fragments
One of the web’s most fundamental features is the ability to link between different documents. There are two primary ways to create links:
Link to the top of a document by providing the document's URL
Link to a specific section of a document by appending a document fragment (ID) to the URL
Create and use text fragments in Firefox
- Identify the text to highlight. Choose the exact text you want users to see on the target webpage.
- Create the URL. Use the following syntax to add a text fragment to the URL:
| :~: | Known as the fragment directive, this sequence of characters tells the browser that what comes next is one or more user-agent instructions, which are stripped from the URL during loading so that author scripts cannot directly interact with them. |
| text= | A text directive. This provides a text fragment to the browser, defining what text is to be linked to in the linked document. |
| textStart | A text string specifying the start of the linked text. When used without textEnd it will contain the whole range that must be highlighted. |
| textEnd | A text string specifying the end of the linked text. When textStart and textEnd are both present, they serve as boundary points of a range. |
| prefix- | A text string followed by a hyphen specifying what text should immediately precede the linked text, only allowing for whitespace in between. This helps the browser to select the correct linked text, in cases where there are multiple matches. |
| -suffix | A hyphen followed by a text string specifying what text should immediately follow the linked text, only allowing for whitespace in between. This helps the browser to select the correct linked text, in cases where there are multiple matches. |
- Note: The text strings used for the following parameters must be percent-encoded: textStart, textEnd, prefix, suffix-.
- For example, this highlights the phrase “Firefox Text Fragments” on the page:
-
Test your link: Open the link in Firefox to ensure it highlights the intended text. If the webpage content changes or multiple matches are present, adjust the fragment using a prefix or suffix for greater accuracy.
Practical examples
- Highlight a single word:
-
- This highlights the word “example”.
- Highlight a range of text:
-
- This highlights the text “Text Fragments are useful”.
- Add context for ambiguous matches:
-
- This ensures the specific phrase is highlighted even if similar text exists on the page.
Common questions
What happens if the target text changes?
The text fragment might fail if the target text is removed or altered significantly. Use prefixes and suffixes to improve resilience. If matching fails, the page behaves as if there is no text fragment. If an additional document fragment is present, it is scrolled to, otherwise the page scrolls to the top.
Can I use text fragments with non-text elements?
No. Text fragments only work with selectable text, not images, videos or dynamic elements.
Do all users see the highlight?
Yes, as long as their browser supports text fragments.
What are the limitations of linking to document fragments?
Linking to document fragments requires the page author to define an anchor, such as an id attribute, in the HTML.
If the ID is modified or removed, the link breaks and the user is redirected to the top of the page. While this behavior is an example of graceful degradation, it limits the control of the link author. The ability to link precisely to specific content is at the mercy of the page author’s decisions.
