JavaScript Element part Property

What You’ll Learn

Element.part is a read-only instance property that returns a DOMTokenList of CSS part identifiers. These names let external stylesheets reach into shadow DOM via the ::part() pseudo-element. Learn how to read, add, remove, and toggle parts—with five examples and try-it labs.

Introduction

Shadow DOM encapsulates styles, but sometimes the component author wants to let outside CSS customize specific pieces. That is where CSS Shadow Parts come in: add a part attribute to an element inside a shadow tree, and external selectors like my-elem::part(heading) can style it.

The Element.part property exposes those identifiers as a DOMTokenList, similar to classList. You can read, add, remove, replace, or toggle part names programmatically.

const el = this.shadowRoot.querySelector(".tab");
console.log(el.part);       // DOMTokenList ["tab"]
el.part.add("active");      // now "tab active"
el.part = "tab selected";   // shorthand assignment

Understanding the Property

MDN: the read-only part property of the Element interface contains a DOMTokenList object representing the part identifier(s) of the element. It reflects the element’s part content attribute. These can be used to style parts of a shadow DOM via the ::part pseudo-element.

• Read-only object — you cannot replace the DOMTokenList, but you can mutate it or assign a string to el.part.
• Reflects attribute — mirrors the HTML part attribute.
• Empty by default — length === 0 when no part attribute is set.
• Baseline — widely available since July 2020 (MDN).

📝 Syntax

element.part

Value

A DOMTokenList object. If the part attribute is not set or empty, the returned list has length === 0.

📋 MDN Shadow Parts Example Shape

MDN’s shadow-part example finds elements with a part attribute, then toggles part identifiers on click:

const tabs = [];
const children = this.shadowRoot.children;

for (const elem of children) {
  if (elem.getAttribute("part")) {
    tabs.push(elem);
  }
}

tabs.forEach((tab) => {
  tab.addEventListener("click", (e) => {
    tabs.forEach((t) => { t.part = "tab"; });
    e.target.part = "tab active";
  });
  console.log(tab.part);
});

Related learning: ::part(), exportparts, and innerHTML.

Examples Gallery

Examples follow MDN Element: part. Labs use inline shadow DOM so you can experiment safely.

const el = document.querySelector("[part]");
console.log(el.part);          // DOMTokenList
console.log(el.part.length);   // number of parts
console.log(el.part.value);    // space-separated string

DOMTokenList ["heading"]
1
heading

const el = document.querySelector("[part='tab']");
el.part.add("active");
console.log(el.part.value); // "tab active"
el.part.remove("active");
console.log(el.part.value); // "tab"

tab active
tab

const el = document.querySelector("[part='tab']");
el.part.toggle("active");
console.log(el.part.contains("active")); // true
el.part.toggle("active");
console.log(el.part.contains("active")); // false

true
false

const tabs = this.shadowRoot.querySelectorAll("[part]");
tabs.forEach((tab) => {
  tab.addEventListener("click", (e) => {
    tabs.forEach((t) => { t.part = "tab"; });
    e.target.part = "tab active";
  });
});

Tab 1 parts: tab
Tab 2 parts: tab active
Tab 3 parts: tab

console.log({
  supported: "part" in Element.prototype,
  returns: "DOMTokenList (like classList)",
  cssHook: "::part(name)",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "returns": "DOMTokenList (like classList)",
  "cssHook": "::part(name)",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Theming a web component’s internals from the host page CSS.
• Toggling active / selected states on shadow-DOM tabs or navigation items.
• Exposing specific inner elements for consumer customization without breaking encapsulation.
• Building design-system components that ship default styles but allow overrides via ::part().
• Combining with exportparts to re-export parts from nested shadow trees.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available since July 2020).
• The property itself is read-only, but you can assign a string to el.part (sets value) or call add(), remove(), toggle(), replace().
• ::part() does not pierce nested shadow boundaries. Use exportparts on intermediate hosts to re-export inner parts.
• Setting part on regular (non-shadow) elements has no CSS effect; ::part() only works across shadow boundaries.
• Related: outerHTML, innerHTML, prefix, JavaScript hub.

💡 Best Practices