Abstract
Text Fragments adds support for specifying a text snippet in the URL fragment. When navigating to a URL with such a fragment, the user agent can quickly emphasise and/or bring it to the user’s attention.
2.1.2. User sharing
With text fragments, browsers may implement an option to ‘Copy URL to here’ when the user opens the context menu on a text selection. The browser can then generate a URL with the text selection appropriately specified, and the recipient of the URL will have the specified text conveniently indicated. Without text fragments, if a user wants to share a passage of text from a page, they would likely just copy and paste the passage, in which case the receiver loses the context of the page.
This specification intentionally doesn’t define what actions a user agent should or could take to “indicate” a text match. There are different experiences and trade-offs a user agent could make. Some examples of possible actions:
- Providing visual emphasis or highlight of the text passage
- Automatically scrolling the passage into view when the page is navigated
- Activating a UA’s find-in-page feature on the text passage
- Providing a “Click to scroll to text passage” notification
- Providing a notification when the text passage isn’t found in the page
3.2. Syntax
A text fragment directive is specified in the fragment directive (see § 3.3 The Fragment Directive) with the following format:
#:~:text=[prefix-,]textStart[,textEnd][,-suffix]
context |-------match-----| context
(Square brackets indicate an optional parameter)
The text parameters are percent-decoded before matching. Dash (-), ampersand (&), and comma (,) characters in text parameters must be percent-encoded to avoid being interpreted as part of the text directive syntax.
The only required parameter is textStart. If only textStart is specified, the first instance of this exact text string is the target text.
#:~:text=an%20example%20text%20fragment indicates that the exact text “an example text fragment” is the target text.If the textEnd parameter is also specified, then the text directive refers to a range of text in the page. The target text range is the text range starting at the first instance of startText, until the first instance of endText that appears after startText. This is equivalent to specifying the entire text range in the startText parameter, but allows the URL to avoid being bloated with a long text directive.
#:~:text=an%20example,text%20fragment indicates that the first instance of “an example” until the following first instance of “text fragment” is the target text.3.2.1. Context Terms
The other two optional parameters are context terms. They are specified by the dash (-) character succeeding the prefix and preceding the suffix, to differentiate them from the textStart and textEnd parameters, as any combination of optional parameters may be specified.
Context terms are used to disambiguate the target text fragment. The context terms can specify the text immediately before (prefix) and immediately after (suffix) the text fragment, allowing for whitespace.
The context terms are not part of the targeted text fragment and must not be visually indicated.
#:~:text=this%20is-,an%20example,-text%20fragment would match to “an example” in “this is an example text fragment”, but not match to “an example” in “here is an example text”.