Text Fragments

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

2. Introduction

2.1. Use cases

2.1.1. Web text references

2.1.2. User sharing

3. Description

3.1. Indication

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.

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 textStart, until the first instance of textEnd that appears after textStart. This is equivalent to specifying the entire text range in the textStart parameter, but allows the URL to avoid being bloated with a long text directive.

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.

3.2.2. BiDi Considerations

Since URL strings are ASCII encoded, they provide no built-in support for bi-directional text. However, the content that we wish to target on a page may be LTR (left-to-right), RTL (right-to-left) or both (Bidirectional/BiDi). This section provides an intuitive description the behavior implicitly described by the normative sections further in this spec.

The characters of each term in the text fragment are in logical order, that is, the order in which a native reader would read them in (and also the order in which characters are stored in memory).

Similarly, the prefix and textStart terms identify text coming before another term in logical order, while suffix and textEnd follow other terms in logical order.

Note: user agents may visually render URLs in a manner friendlier to a native reader, for example, by converting the displayed string to Unicode. However, the string representation of a URL remains plain ASCII characters.

3.3. The Fragment Directive

To avoid compatibility issues with usage of existing URL fragments, this spec introduces the fragment directive. The fragment directive is a portion of the URL fragment that follows the fragment directive delimiter.

The fragment directive delimiter is the string ":~:", that is the three consecutive code points U+003A (:), U+007E (~), U+003A (:).

The fragment directive is meant to carry instructions, such as text=, for the UA rather than for the document.

To prevent impacting page operation, it is stripped from a Document's URL so that author scripts can’t directly interact with it. This also ensures future directives could be added without introducing breaking changes to existing content. Potential examples could be: image-fragments, translation-hints.

3.3.1. Processing the fragment directive

The fragment directive is processed and removed from the fragment whenever the UA sets the URL on a Document. This is defined with the following additions and changes.

To the definition of Document, add:

Monkeypatching [DOM]:

Each document has an associated fragment directive which is either null or an ASCII string holding data used by the UA to process the resource. It is initially null.

Whenever the fragment directive is stripped from the URL, it is set to the Document’s fragment directive.

Add a series of steps that will process a fragment directive on a URL:

Monkeypatching [DOM]:

To process and consume fragment directive from a URL url and Document document, run these steps:

1. Let raw fragment be equal to url’s fragment.

2. If raw fragment is non-null and contains the fragment directive delimiter as a substring:

   1. Let fragmentDirectivePosition be the index of the first instance of the fragment directive delimiter in raw fragment.

   2. Let fragment be the substring of raw fragment starting at 0 of count fragmentDirectivePosition.

   3. Advance fragmentDirectivePosition by the length of fragment directive delimiter.

   4. Let fragment directive be the substring of raw fragment starting at fragmentDirectivePosition.

   5. Set url’s fragment to fragment.

   6. Set document’s fragment directive to fragment directive.

      This is stored on the document but currently not web-exposed

Amend the create and initialize a Document object steps to parse and remove the fragment directive by inserting the following steps right before the setting document’s URL (currently step 9):

Monkeypatching [HTML]:

9. Run the process and consume fragment directive steps on creationURL and document.

10. Set document’s URL to be creationURL.

Amend the traverse the history steps to process the fragment directive during a history navigation by inserting steps before setting the newDocument’s URL (currently step 6).

Monkeypatching [HTML]:

6. Let processedURL be a copy of entry’s URL.

7. Run the process and consume fragment directive steps on processedURL and document.

8. Set newDocument’s URL to processedURL.

  window.location = 'https://example.com#foo:~:bar';

  console.log(window.location.href); // 'https://example.com#foo'
  console.log(window.location.hash); // '#foo'

  window.location.hash = 'fizz:~:buzz';
  console.log(window.location.href); // 'https://example.com#fizz'
  console.log(window.location.hash); // '#fizz'

  onhashchange = () => {console.log('HASHCHANGE');};
  window.location.hash = 'fizz:~:zillch'; // 'HASHCHANGE'
  console.log(window.location.href); // 'https://example.com#fizz'
  console.log(window.location.hash); // '#fizz'

  let url = new URL('https://example.com#foo:~:bar');
  console.log(url.href); // 'https://example.com#foo:~:bar'
  console.log(url.hash); // '#foo:~:bar'

  document.url = url;
  console.log(document.url.href); // 'https://example.com#foo:~:bar'
  console.log(document.url.hash); // '#foo:~:bar'

  <a id='anchor' href="https://example.com#foo:~:bar">Anchor</a>
  <script>
    console.log(anchor.href); // 'https://example.com#foo:~:bar'
    console.log(anchor.hash); // '#foo:~:bar'
  </script>

  history.pushState({}, 'title', 'index.html#foo:~:bar');
  window.location = 'newpage.html';
  // on newpage.html
  history.back();

3.3.2. Parsing the fragment directive

A ParsedTextDirective is a struct that consists of four strings: textStart, textEnd, prefix, and suffix. textStart is required to be non-null. The other three items may be set to null, indicating they weren’t provided. The empty string is not a valid value for any of these items.

See § 3.2 Syntax for the what each of these components means and how they’re used.

3.3.3. Fragment directive grammar

A valid fragment directive is a sequence of characters that appears in the fragment directive that matches the production:

FragmentDirective ::=

(TextDirective | UnknownDirective) ("&" FragmentDirective)?

UnknownDirective ::=

CharacterString

CharacterString ::=

(ExplicitChar | PercentEncodedChar)+

ExplicitChar ::=

[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" | ";" | "=" | "?" | "@" | "_" | "~" | "&" | "," | "-"

An ExplicitChar may be any URL code point.

The text fragment directive is one such fragment directive that enables specifying a piece of text on the page, that matches the production:

TextDirective ::=

"text=" TextDirectiveParameters

TextDirectiveParameters ::=

(TextDirectivePrefix ",")? TextDirectiveString ("," TextDirectiveString)? ("," TextDirectiveSuffix)?

TextDirectivePrefix ::=

TextDirectiveString"-"

TextDirectiveSuffix ::=

"-"TextDirectiveString

TextDirectiveString ::=

(TextDirectiveExplicitChar | PercentEncodedChar)+

TextDirectiveExplicitChar ::=

[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" | ";" | "=" | "?" | "@" | "_" | "~"

A TextDirectiveExplicitChar may be any URL code point that is not explicitly used in the TextDirective syntax, that is "&", "-", and ",", which must be percent-encoded.

PercentEncodedChar ::=

"%" [a-zA-Z0-9]+

3.4. Security and Privacy

3.4.1. Motivation

Care must be taken when implementing text fragment directive so that it cannot be used to exfiltrate information across origins. Scripts can navigate a page to a cross-origin URL with a text fragment directive. If a malicious actor can determine that the text fragment was successfully found in victim page as a result of such a navigation, they can infer the existence of any text on the page.

The following subsections restrict the feature to mitigate the expected attack vectors. In summary, the text fragment directives are invoked only on full (non-same-page) navigations that are the result of a user activation. Additionally, navigations originating from a different origin than the destination will require the navigation to take place in a "noopener" context, such that the destination page is known to be sufficiently isolated.

3.4.2. Scroll On Navigation

A UA may choose to automatically scroll a matched text passage into view. This can be a convenient experience for the user but does present some risks that implementing UAs should be aware of.

There are known (and potentially unknown) ways a scroll on navigation might be detectable and distinguished from natural user scrolls.

All known cases like this rely on specific circumstances about the target page so don’t apply generally. With additional restrictions about when the text fragment can invoke an attacker is further restricted. Nonetheless, different UAs can come to different conclusions about whether these risks are acceptable. UAs should consider these factors when determining whether to scroll as part of navigating to a text fragment.

Conforming UAs may choose not to scroll automatically on navigation. Such UAs may, instead, provide UI to initiate the scroll ("click to scroll") or none at all. In these cases UA should provide some indication to the user that an indicated passage exists further down on the page.

The examples above illustrate that in specific circumstances, it may be possible for an attacker to extract 1 bit of information about content on the page. However, care must be taken so that such opportunities cannot be exploited to extract arbitrary content from the page by repeating the attack. For this reason, restrictions based on user activation and browsing context isolation are very important and must be implemented.

If a UA does choose to scroll automatically, it must ensure no scrolling is performed while the document is in the background (for example, in an inactive tab). This ensures any malicious usage is visible to the user and prevents attackers from trying to secretly automate a search in background documents.

3.4.3. Search Timing

A naive implementation of the text search algorithm could allow information exfiltration based on runtime duration differences between a matching and non- matching query. If an attacker could find a way to synchronously navigate to a text fragment directive-invoking URL, they would be able to determine the existence of a text snippet by measuring how long the navigation call takes.

For this reason, the implementation must ensure the runtime of § 3.5 Navigating to a Text Fragment steps does not differ based on whether a match has been successfully found.

This specification does not specify exactly how a UA achieves this as there are multiple solutions with differing tradeoffs. For example, a UA may continue to walk the tree even after a match is found in find a range from a text directive. Alternatively, it may schedule an asynchronous task to find and set the indicated part of the document.

3.4.4. Restricting the Text Fragment

Amend the definition of a request and of a Document to include a new field for the textFragmentToken:

Monkeypatching [FETCH]:

A request has an associated textFragmentToken flag

Monkeypatching [HTML]:

A Document has a textFragmentToken flag that is consumed in order to allow a single activation of a text fragment. This flag is generated only during loading if the navigation occurs as a result of a user activation.

If the Document's textFragmentToken isn’t consumed to activate a text fragment, it may be consumed to set the textFragmentToken flag of a navigation request. In this way, a textFragmentToken can be propagated from one Document to another across a navigation.

Reading either the Document's textFragmentToken or the request's textFragmentToken must always consume the value, such that the token cannot be cloned.

A textFragmentToken is generated when a Document is loaded as a result of a user gesture. It grants its holder permission (in terms of user activation) to activate a single text fragment. Alternatively, it may be propagated through a navigation to allow a future document to activate a text fragment from this navigation’s user gesture.

This mechanism allows text fragments to activate through a common redirect technique used by many popular web sites. Such sites redirect users to their intended destination by responding with a 200 status code containing script to set the window.location .

Unlike real HTTP ( status 3xx ) redirects, these "client-side" redirects cannot propagate the fact that the navigation is the result of a user gesture. The textFragmentToken mechanism allows passing through this specifically scoped user-activation through such navigations. This means a page can programmatically navigate to a text fragment, a single time, as if it has a user gesture. However, further navigations require a new user gesture.

The following diagram demonstrates how the token is used to activate a text fragment through a client-side redirect service:

See redirects.md for a more in-depth discussion.

Monkeypatching [HTML]:

A Document has an allowTextFragmentDirective flag that is used to determine whether a text fragment directive should be allowed to activate. If this flag is false, the text fragment must not cause any observable effects.

Amend the create and initialize a Document object steps by adding the following steps before returning document:

Monkeypatching [HTML]:

15. Set the textFragmentToken flag on document:

    1. Let is user activated be true if the current navigation was initiated from a window that had a transient activation at the time the navigation was initiated, or the UA has reason to believe it comes from a direct user gesture (e.g. user typed into the address bar).

       TODO: it’d be better to refer to the userActivationFlag on the request. See Sec-Fetch-User in [FETCH-METADATA].

    2. If browsing context is a top-level browsing context and if either of is user activated or the textFragmentToken flag of navigationParam’s request object is true, set the document’s textFragmentToken flag to true. Otherwise, set it to false.

       It’s important that the token not be copyable so that at most one token is created per user-activated navigation.

16. Set the allowTextFragmentDirective flag on document by following these sub-steps:

    1. If document’s fragment directive field is null or empty, set allowTextFragmentDirective to false and abort these sub-steps.

    2. Let textFragmentToken be the value of document’s textFragmentToken and set document’s textFragmentToken to false.

    3. If the navigationParam’s request has a sec-fetch-site header and its value is "none" set allowTextFragmentDirective to true and abort these sub-steps.

       If a navigation originates from browser UI, it’s always ok to allow it since it’ll be user triggered and the page/script isn’t providing the text snippet.

       Note: Depending on the UA, there may be cases where the incumbentNavigationOrigin parameter is null but it’s not clear that the navigation should be considered as initiated from browser UI. E.g. an "open in new window" context menu item when right clicking on a link. The intent in this item is to distinguish cases where the app/page is able to set the URL from those that are fully under the user’s control. In the former we want to prevent activation of the text fragment unless the destination is loaded in a separate browsing context group (so that the source cannot both control the text snippet and observe side-effects in the navigation).

       See sec-fetch-site for a more detailed discussion of how this should apply.

    4. If textFragmentToken is false, set allowTextFragmentDirective to false and abort these sub-steps.

    5. If the document of the latest entry in document’s browsing context's session history is equal to document, set allowTextFragmentDirective to false and abort these sub-steps.

       i.e. Forbidden on a same-document navigation.

    6. If the navigationParam’s request has a sec-fetch-site header and its value is "same-origin" set allowTextFragmentDirective to true and abort these sub-steps.

    7. If document’s browsing context is a top-level browsing context and its group’s browsing context set has length 1, set allowTextFragmentDirective to true and abort these sub-steps.

       i.e. Only allow navigation from a cross-origin element/script if the document is loaded in a noopener context. That is, a new top level browsing context group to which the navigator does not have script access and which may be placed into a separate process.

    8. Otherwise, set allowTextFragmentDirective to false.

Amend step 2 of the process a navigate fetch steps to additionally set request’s textFragmentToken to the value of the active document's textFragmentToken and set the active document's value to false.

Monkeypatching [HTML]:

2. Set request’s client to sourceBrowsingContext’s active document’s relevant settings object, destination to "document", mode to "navigate", credentials mode to "include", use-URL-credentials flag, redirect mode to "manual", replaces client id to browsingContext’s active document’s relevant settings object’s id, and textFragmentToken to sourceBrowsingContext’s active document’s textFragmentToken. Set sourceBrowsingContext’s active document’s textFragmentToken to false.

Amend the try to scroll to the fragment steps by replacing the steps of the task queued in step 2:

Monkeypatching [HTML]:

1. If document has no parser, or its parser has stopped parsing, or the user agent has reason to believe the user is no longer interested in scrolling to the fragment, then clear document’s allowTextFragmentDirective flag and abort these steps.

2. Scroll to the fragment given in document’s URL. If this does not find an indicated part of the document, then try to scroll to the fragment for document.

3. Clear document’s allowTextFragmentDirective flag

3.5. Navigating to a Text Fragment

Replace step 3.1 of the scroll to the fragment algorithm with the following:

Monkeypatching [HTML]:

1. Let target, range be the element and range that is the indicated part of the document.

Replace step 3.3 of the scroll to the fragment algorithm with the following:

Monkeypatching [HTML]:

3. Get the policy value for force-load-at-top in the Document. If the result is true, abort these steps.

4. If range is non-null:

   1. If the UA supports scrolling of text fragments on navigation, invoke Scroll range into view, with range range, containingElement target, behavior set to "auto", block set to "center", and inline set to "nearest".

5. Otherwise:

   1. Scroll target into view, with behavior set to "auto", block set to "start", and inline set to "nearest".

      This otherwise case is the same as the current step 3.3.

Add the following steps to the beginning of the processing model for the indicated part of the document:

Monkeypatching [HTML]:

1. Let fragment directive string be the document’s fragment directive.

2. If the document’s allowTextFragmentDirective flag is true then:

   1. Let ranges be a list that is the result of running the process a fragment directive steps with fragment directive string and the document.

   2. If ranges is non-empty, then:

      1. Let range be the first item of ranges.

         The first range in ranges is specifically scrolled into view. This range, along with the remaining ranges should be visually indicated in a way that is not revealed to script, which is left as UA-defined behavior.

      2. Let node be the first common ancestor of range’s start node and end node.

      3. While node is non-null and is not an element, set node to node’s parent.

      4. The indicated part of the document is node and range; return.

3.5.1. Scroll a DOMRect into view

Move the scroll an element into view algorithm’s steps 3-14 into a new algorithm scroll a DOMRect into view, with input DOMRect bounding box, ScrollIntoViewOptions dictionary options, and element startingElement.

Also move the recursive behavior described at the top of the scroll an element into view algorithm to the scroll a DOMRect into view algorithm: "run these steps for each ancestor element or viewport of startingElement that establishes a scrolling box scrolling box, in order of innermost to outermost scrolling box".

Monkeypatching [CSSOM-VIEW]:

To scroll a DOMRect into view given a DOMRect bounding box, a scroll behavior behavior, a block flow direction position block, and an inline base direction position inline, and element startingElement, means to run these steps for each ancestor element or viewport of startingElement that establishes a scrolling box scrolling box, in order of innermost to outermost scrolling box:

OMITTED

TODO: There’s more to do here since the bounding box needs to be transformed with each step to an ancestor element or viewport.

Replace steps 3-14 of the scroll an element into view algorithm with a call to scroll a DOMRect into view:

Monkeypatching [CSSOM-VIEW]:

To scroll an element into view element, with a scroll behavior behavior, a block flow direction position block, and an inline base direction position inline, means to run these steps:

1. If the Document associated with element is not same origin with the Document associated with the element or viewport associated with box, terminate these steps.

2. Let element bounding border box be the box that the return value of invoking getBoundingClientRect() on element represents.

3. Perform scroll a DOMRect into view given element bounding border box, options and element.

Define a new algorithm for scrolling Range into view:

Monkeypatching [CSSOM-VIEW]:

To scroll a Range into view, with input range range, scroll behavior behavior, a block flow direction position block, an inline base direction position inline, and an element containingElement:

1. Let bounding rect be the DOMRect that is the return value of invoking getBoundingClientRect() on range.

2. Perform scroll a DOMRect into view given bounding rect, behavior, block, inline, and containingElement.

3.5.2. Finding Ranges in a Document

text=prefix-,foo&unknown&text=bar,baz

text=prefix-,foo
text=bar,baz

:~:text=The quick,lazy dog

    <div>The<div> </div>quick brown fox</div>
    <div>jumped over the lazy dog</div>

    <div>The quick brown fox</div>
    <div>jumped over the lazy dog</div>

      <div>
        a<em>b</em>c<div>d</div>e
      </div>

A node is search invisible if it is an element in the HTML namespace and meets any of the following conditions:

1. The computed value of its display property is none.

2. If the node serializes as void.

3. Is any of the following types: HTMLIFrameElement, HTMLImageElement, HTMLMeterElement, HTMLObjectElement, HTMLProgressElement, HTMLStyleElement, HTMLScriptElement, HTMLVideoElement, HTMLAudioElement

4. Is a select element whose multiple content attribute is absent.

A node is part of a non-searchable subtree if it is or has a shadow-including ancestor that is search invisible.

A node is a visible text node if it is a Text node, the computed value of its parent element's visibility property is visible, and it is being rendered.

A node has block-level display if it is an element and the computed value of its display property is any of block, table, flow-root, grid, flex, list-item.

3.5.3. Word Boundaries

A word boundary is defined in [UAX29] in Unicode Text Segmentation § Word_Boundaries. Unicode Text Segmentation § Default_Word_Boundaries defines a default set of what constitutes a word boundary, but as the specification mentions, a more sophisticated algorithm should be used based on the locale.

Dictionary-based word bounding should take specific care in locales without a word-separating character. E.g. In English, words are separated by the space character (' '); however, in Japanese there is no character that separates one word from the next. In such cases, and where the alphabet contains fewer than 100 characters, the dictionary must not contain more than 20% of the alphabet as valid, one-letter words.

A locale is a string containing a valid [BCP47] language tag, or the empty string. An empty string indicates that the primary language is unknown.

A substring is word bounded in a string text, given locales startLocale and endLocale, if both the position of its first character is at a word boundary given startLocale, and the position after its last character is at a word boundary given endLocale.

A number position is at a word boundary in a string text, given a locale locale, if, using locale, either a word boundary immediately precedes the positionth code unit, or text’s length is more than 0 and position equals either 0 or text’s length.

3.6. Indicating The Text Match

The UA may choose to scroll the text fragment into view as part of the try to scroll to the fragment steps or by some other mechanism; however, it is not required to scroll the match into view.

The UA should visually indicate the matched text in some way such that the user is made aware of the text match, such as with a high-contrast highlight.

The UA should provide to the user some method of dismissing the match, such that the matched text no longer appears visually indicated.

The exact appearance and mechanics of the indication are left as UA-defined. However, the UA must not use the Document’s selection to indicate the text match as doing so could allow attack vectors for content exfiltration.

The UA must not visually indicate any provided context terms.

Since the indicator is not part of the document’s content, UAs should consider ways to differentiate it from the page’s content as perceived by the user.

3.6.1. URLs in UA features

UAs provide a number of consumers for a document’s URL (outside of programmatic APIs like window.location). Examples include a location bar indicating the URL of the currently visible document, or the URL used when a user requests to create a bookmark for the current page.

To avoid user confusion, UAs should be consistent in whether such URLs include the fragment directive. This section provides a default set of recommendations for how UAs should handle these cases.

The general principle is that a URL should include the fragment directive only while the visual indicator is visible (i.e. not dismissed). If the user dismisses the indicator, the URL should not include the fragment directive.

If the URL includes a text fragment but a match wasn’t found in the current page, the UA may choose to omit it from the exposed URL.

A few common examples are provided below.

3.6.1.1. Location Bar

The location bar’s URL should include a text fragment while it is visually indicated. The fragment directive should be stripped from the location bar URL when the user dismisses the indication.

It is recommended that the text fragment be displayed in the location bar’s URL even if a match wasn’t located in the document.

3.6.1.2. Bookmarks

Many UAs provide a "bookmark" feature allowing users to store a convenient link to the current page in the UA’s interface.

A newly created bookmark should, by default, include the fragment directive in the URL if, and only if, a match was found and the visual indicator hasn’t been dismissed.

Navigating to a URL from a bookmark should process a fragment directive as if it were navigated to in a typical navigation.

3.6.1.3. Sharing

Some UAs provide a method for users to share the current page with others, typically by providing the URL to another app or messaging service.

When providing a URL in these situations, it should include the fragment directive if, and only if, a match was found and the visual indicator hasn’t been dismissed.

3.7. Document Policy Integration

This specification defines a configuration point in Document Policy with name "force-load-at-top". Its type is boolean with default value false.

  Document-Policy: force-load-at-top

Fragment-based scroll blocking from this policy is specified in an amendment to the scroll to the fragment algorithm in the § 3.5 Navigating to a Text Fragment section of this document.

History scroll restoration is blocked by amending the restore persisted state steps by inserting a new step after 2:

3. Get the document policy value of the "force-load-at-top" feature for the Document. If the result is true, then the user agent should not restore the scroll position for the Document or any of its scrollable regions. Scroll positions for child browsing contexts should be restored based on the value of this policy in the child Document.

3.8. Feature Detectability

For feature detectability, we propose adding a new FragmentDirective interface that is exposed via document.fragmentDirective if the UA supports the feature.

[Exposed=Window]
interface FragmentDirective {
};

We amend the Document interface to include a fragmentDirective property:

partial interface Document {
    [SameObject] readonly attribute FragmentDirective fragmentDirective;
};

This object may be used to expose additional information about the text fragment or other fragment directives in the future.

4. Generating Text Fragment Directives

This section contains recommendations for UAs automatically generating URLs with a text fragment directive. These recommendations aren’t normative but are provided to ensure generated URLs result in maximally stable and usable URLs.

4.1. Prefer Exact Matching To Range-based

The match text can be provided either as an exact string "text=foo%20bar%20baz" or as a range "text=foo,bar".

UAs should prefer to specify the entire string where practical. This ensures that if the destination page is removed or changed, the intended destination can still be derived from the URL itself.

The first recorded idea of using digital electronics for computing was the
1931 paper "The Use of Thyratrons for High Speed Automatic Counting of
Physical Phenomena" by C. E. Wynn-Williams.

Range-based matches can be helpful when the quoted text is excessively long and encoding the entire string would produce an unwieldy URL.

It is recommended that text snippets shorter than 300 characters always be encoded using an exact match. Above this limit, the UA should encode the string as a range-based match.

4.2. Use Context Only When Necessary

Context terms allow the text fragment directive to disambiguate text snippets on a page. However, their use can make the URL more brittle in some cases. Often, the desired string will start or end at an element boundary. The context will therefore exist in an adjacent element. Changes to the page structure could invalidate the text fragment directive since the context and match text may no longer appear to be adjacent.

<div class="section">HEADER</div>
<div class="content">Text to quote</div>

text=HEADER-,Text%20to%20quote

Where a text snippet is long enough and unique, a UA should prefer to avoid adding superfluous context terms.

It is recommended that context should be used only if one of the following is true:

• The UA determines the quoted text is ambiguous
• The quoted text contains 3 or fewer words

4.3. Determine If Fragment Id Is Needed

When the UA navigates to a URL containing a text fragment directive, it will fallback to scrolling into view a regular element-id based fragment if it exists and the text fragment isn’t found.

This can be useful to provide a fallback, in case the text in the document changes, invalidating the text fragment directive.

The earliest known tool for use in computation is the Sumerian abacus

However, UAs should take care that the fallback element-id fragment is the correct one:

By the late 1960s, computer systems could perform symbolic algebraic
manipulations

If a UA chooses not to scroll text fragments into view on navigation (reasons why a UA may make this choice are discussed in § 3.4 Security and Privacy), it must scroll the element-id into view, if provided, regardless of whether a text fragment was matched. Not doing so would allow detecting the text fragment match based on whether the element-id was scrolled.