Element.part — Eigenschaft · JavaScript-Referenz

Signatur

Element.part

Beschreibung

Die Eigenschaft Element.part gibt eine lebendige DOMTokenList zurück, die die durch Leerzeichen getrennten Werte des HTML-Attributs part abbildet. Diese Teil-Namen machen Elemente innerhalb eines Shadow-Baums für das Styling von außen sichtbar: Mit dem CSS-Pseudoelement ::part(name) kann das umgebende Dokument gezielt einzelne interne Elemente einer Web Component gestalten, ohne die Kapselung komplett aufzubrechen.

Die Eigenschaft selbst ist schreibgeschützt – man kann ihr keine neue Liste zuweisen –, die zurückgegebene Liste lässt sich aber über add(), remove(), toggle(), replace() und contains() verändern bzw. abfragen. Jede Änderung wird direkt ins part-Attribut zurückgeschrieben. Das Prinzip ist dasselbe wie bei Element.classList.

Typische Einsatzfälle sind Custom Elements, deren interne Bausteine (z. B. Beschriftung, Icon, Button) von Nutzern der Komponente gestaltbar sein sollen, oder Zustände, die man über dynamische Teil-Namen nach außen meldet (etwa part="tab active"). Dadurch entsteht eine klar definierte, dokumentierte Styling-API der Komponente.

Rückgabewert

Typ

DOMTokenList

Beschreibung

Eine lebendige DOMTokenList mit den Teil-Namen des Elements. Ist kein part-Attribut gesetzt, ist die Liste leer (length === 0).

Beispiele

Teil-Namen auslesen und prüfen

const el = document.createElement('span');
el.setAttribute('part', 'label highlight');

console.log(el.part.length);
console.log(el.part.contains('label'));
console.log([...el.part]);

2 true ["label", "highlight"]

Web Component mit stylbaren Teilen

class FancyButton extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    const btn = document.createElement('button');
    btn.part.add('button');
    const icon = document.createElement('span');
    icon.part.add('icon');
    icon.textContent = '★';
    btn.append(icon, ' Klick mich');
    shadow.append(btn);
  }
}
customElements.define('fancy-button', FancyButton);

// Von außen stylen:
const style = document.createElement('style');
style.textContent = `
  fancy-button::part(button) { background: rebeccapurple; color: white; }
  fancy-button::part(icon) { color: gold; }
`;
document.head.append(style);
document.body.append(document.createElement('fancy-button'));

Zustand über part nach außen melden

const tabs = [...document.querySelector('my-tabs').shadowRoot.querySelectorAll('[part~="tab"]')];

const activate = (index) => {
  tabs.forEach((tab, i) => tab.part.toggle('active', i === index));
};

activate(1);
console.log(tabs[1].getAttribute('part'));
// CSS außen: my-tabs::part(tab active) { font-weight: bold; }

tab active

// Wichtig · Fallstricke

Schreibgeschützt: el.part = 'x' ist wirkungslos (bzw. wird dank [PutForwards=value] in manchen Browsern an value weitergeleitet). Zuverlässig ist el.part.value = 'a b' oder setAttribute('part', …).
Nur im Shadow DOM relevant: ::part() greift nur bei Elementen innerhalb eines Shadow-Baums und nur vom Host aus gesehen. Im normalen Light DOM hat part keinen Styling-Effekt.
Verschachtelte Komponenten: Teile tiefer liegender Shadow-Bäume werden nicht automatisch weitergereicht – dafür braucht man das Attribut exportparts am inneren Host.
::part() erlaubt keine strukturellen Pseudoklassen wie :nth-child() und keine Nachfahren-Selektoren dahinter (::part(x) span ist ungültig); Zustands-Pseudoklassen wie :hover funktionieren dagegen.
Kompatibilität: in allen aktuellen Browsern verfügbar; der Internet Explorer und das alte Edge (EdgeHTML) unterstützen die Eigenschaft nicht.

Siehe auch

Element.classList DOMTokenList Element.attachShadow() ShadowRoot CustomElementRegistry.define() CloseEvent.reason Element.ariaSort