JavaScript Document fragmentDirective Property

What You’ll Learn

Document.fragmentDirective is a read-only instance property that returns a FragmentDirective object. Today it is mainly for feature-detecting text fragments (scroll-to-text links). Learn the URL syntax, why the object is empty, ::target-text styling, and five examples with try-it labs.

Introduction

Classic links jump to an element id with #section. Text fragments go further: a special URL fragment can tell the browser to find a phrase on the page, scroll to it, and highlight it—even when the author never added an id.

MDN: document.fragmentDirective returns the FragmentDirective for the current document. The object is currently empty and is mainly intended for feature detection; in the future it might include other information.

Related Document tutorials: forms, fonts, Document constructor.

Understanding Document.fragmentDirective

A read-only instance property on Document. Its value is a FragmentDirective object (MDN).

• Value — FragmentDirective for this document.
• Empty today — no instance properties or methods listed on MDN.
• Main use — detect text fragment support via existence of the object.
• Future-ready — MDN notes it might hold more information later.
• Not for reading matches — text directives are stripped so scripts cannot directly interact with them (MDN Text fragments).

📝 Syntax

document.fragmentDirective

Value

A FragmentDirective object (MDN).

Feature detection (MDN)

if (document.fragmentDirective) {
  console.log("Your browser supports text fragments.");
} else {
  console.log("Text fragments are not supported in your browser.");
}

🔗 What text fragments look like

A text fragment uses a fragment directive after #:~:. The simplest form highlights a single phrase:

https://example.com/page#:~:text=important%20phrase

More advanced forms can use start/end context and multiple directives. Supporting browsers scroll to the match and apply a highlight you can style with ::target-text.

⚖️ Related pieces of the feature

🎨 Style highlights with ::target-text

When a text fragment match is shown, authors can customize the highlight with the CSS ::target-text pseudo-element (MDN).

::target-text {
  background-color: rebeccapurple;
  color: white;
}

Examples Gallery

Examples follow MDN Document: fragmentDirective and the FragmentDirective interface. Use View Output or Try It Yourself for each case.

if (document.fragmentDirective) {
  console.log("Your browser supports text fragments.");
} else {
  console.log("Text fragments are not supported in your browser.");
}

Your browser supports text fragments.

const supported = "fragmentDirective" in document;
console.log("in document?", supported);
console.log("typeof:", typeof document.fragmentDirective);
console.log("value:", document.fragmentDirective);

in document? true
typeof: object
value: FragmentDirective {}

if (!document.fragmentDirective) {
  console.log("Not supported");
} else {
  const keys = Object.keys(document.fragmentDirective);
  console.log("own keys:", keys);
  console.log("keys length:", keys.length); // 0 today
}

own keys: 
keys length: 0

function textFragmentUrl(pageUrl, phrase) {
  const encoded = encodeURIComponent(phrase);
  return `${pageUrl}#:~:text=${encoded}`;
}

const link = textFragmentUrl(
  "https://example.com/article",
  "important phrase"
);
console.log(link);
// https://example.com/article#:~:text=important%20phrase

https://example.com/article#:~:text=important%20phrase

::target-text {
  background-color: rebeccapurple;
  color: white;
}

// CSS does the visual work when a #:~:text= link is opened.
// JS only detects support:
console.log(!!document.fragmentDirective);

true
(::target-text rule ready for fragment matches)

🚀 Common Use Cases

• Feature detection — show “Copy text link” only when supported.
• Docs / knowledge bases — share deep links to exact sentences.
• Search result previews — open articles at the matched quote.
• Design polish — brand the highlight with ::target-text.
• Progressive enhancement — fall back to classic #id links.
• Not for reading the match in JS — directives are stripped from the URL (MDN).

📝 Notes

• MDN: Baseline 2025 newly available (since March 2025) — no Deprecated / Experimental / Non-standard banner.
• Object is empty today; mainly for feature detection (MDN).
• FragmentDirective lists no properties or methods (MDN).
• Style matches with ::target-text.
• Related: forms, fonts, Document constructor.

💡 Best Practices