The part Attribute

The `part` Attribute

Global Attribute

The part attribute exposes elements inside a Web Component’s Shadow DOM for styling from outside the component. It enables theme-ability and customization while maintaining encapsulation, allowing component users to style specific parts without breaking the component’s internal structure.

Syntax

<!-- Inside shadow DOM -->
<button part="button">Click me</button>
<span part="label icon">Text with icon</span>

<!-- Outside, in light DOM CSS -->
<style>
  my-component::part(button) {
    background: blue;
  }
</style>

Values

Value	Description
Part name (string)	Name to expose for styling (space-separated for multiple parts)

Examples

Basic Themeable Button

<!DOCTYPE html>
<html>
<head>
<style>
  /* Style the button part from outside */
  theme-button::part(button) {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    border: none;
    padding: 12px 24px;
    border-radius: 8px;
    font-size: 16px;
    font-weight: 600;
    cursor: pointer;
    transition: transform 0.2s;
  }

  theme-button::part(button):hover {
    transform: translateY(-2px);
  }

  theme-button::part(icon) {
    margin-right: 8px;
  }

  /* Second button with different theme */
  .success-theme::part(button) {
    background: #10b981;
  }

  .danger-theme::part(button) {
    background: #ef4444;
  }
</style>
</head>
<body>
<h2>Themeable Buttons with CSS Parts</h2>

<div style="padding: 20px; display: flex; gap: 15px; flex-wrap: wrap;">
  <theme-button>Default Theme</theme-button>
  <theme-button class="success-theme">Success Theme</theme-button>
  <theme-button class="danger-theme">Danger Theme</theme-button>
</div>

<script>
  class ThemeButton extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });

      shadow.innerHTML = `
        <button part="button">
          <span part="icon">🎨</span>
          <span part="label"><slot></slot></span>
        </button>
      `;
    }
  }

  customElements.define('theme-button', ThemeButton);
</script>
</body>
</html>

Result

Interactive code playground requires JavaScript. Here's the code:

<!DOCTYPE html>
<html>
<head>
<style>
  /* Style the button part from outside */
  theme-button::part(button) {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    border: none;
    padding: 12px 24px;
    border-radius: 8px;
    font-size: 16px;
    font-weight: 600;
    cursor: pointer;
    transition: transform 0.2s;
  }

  theme-button::part(button):hover {
    transform: translateY(-2px);
  }

  theme-button::part(icon) {
    margin-right: 8px;
  }

  /* Second button with different theme */
  .success-theme::part(button) {
    background: #10b981;
  }

  .danger-theme::part(button) {
    background: #ef4444;
  }
</style>
</head>
<body>
<h2>Themeable Buttons with CSS Parts</h2>

<div style="padding: 20px; display: flex; gap: 15px; flex-wrap: wrap;">
  <theme-button>Default Theme</theme-button>
  <theme-button class="success-theme">Success Theme</theme-button>
  <theme-button class="danger-theme">Danger Theme</theme-button>
</div>

<script>
  class ThemeButton extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });

      shadow.innerHTML = `
        <button part="button">
          <span part="icon">🎨</span>
          <span part="label"><slot></slot></span>
        </button>
      `;
    }
  }

  customElements.define('theme-button', ThemeButton);
</script>
</body>
</html>

Styled Card Component

<!DOCTYPE html>
<html>
<head>
<style>
  /* Theme 1: Blue */
  styled-card::part(container) {
    border: 2px solid #3b82f6;
    border-radius: 12px;
    max-width: 400px;
    margin: 15px;
    overflow: hidden;
    box-shadow: 0 4px 6px rgba(0,0,0,0.1);
  }

  styled-card::part(header) {
    background: #3b82f6;
    color: white;
    padding: 20px;
  }

  styled-card::part(title) {
    margin: 0;
    font-size: 20px;
  }

  styled-card::part(body) {
    padding: 20px;
  }

  styled-card::part(footer) {
    background: #f1f5f9;
    padding: 15px 20px;
    border-top: 2px solid #e2e8f0;
  }

  /* Theme 2: Dark */
  .dark-theme::part(container) {
    border-color: #1e293b;
    background: #1e293b;
    color: white;
  }

  .dark-theme::part(header) {
    background: #0f172a;
  }

  .dark-theme::part(body) {
    background: #1e293b;
  }

  .dark-theme::part(footer) {
    background: #0f172a;
    border-top-color: #334155;
  }

  /* Theme 3: Green */
  .success-theme::part(header) {
    background: #10b981;
  }

  .success-theme::part(container) {
    border-color: #10b981;
  }
</style>
</head>
<body>
<h2>Themed Cards with CSS Parts</h2>

<div style="display: flex; gap: 20px; flex-wrap: wrap;">
  <styled-card>
    <span slot="title">Blue Theme</span>
    <p slot="content">This card uses the default blue theme styling.</p>
    <button slot="action">Learn More</button>
  </styled-card>

  <styled-card class="dark-theme">
    <span slot="title">Dark Theme</span>
    <p slot="content">This card uses the dark theme styling.</p>
    <button slot="action" style="background: #3b82f6; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">Learn More</button>
  </styled-card>

  <styled-card class="success-theme">
    <span slot="title">Success Theme</span>
    <p slot="content">This card uses the success theme styling.</p>
    <button slot="action" style="background: #10b981; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">Learn More</button>
  </styled-card>
</div>

<script>
  class StyledCard extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });

      shadow.innerHTML = `
        <style>
          .container {
            background: white;
          }
        </style>

        <div class="container" part="container">
          <div part="header">
            <h3 part="title">
              <slot name="title">Card Title</slot>
            </h3>
          </div>
          <div part="body">
            <slot name="content">Card content goes here</slot>
          </div>
          <div part="footer">
            <slot name="action"></slot>
          </div>
        </div>
      `;
    }
  }

  customElements.define('styled-card', StyledCard);
</script>
</body>
</html>

Result

Interactive code playground requires JavaScript. Here's the code:

<!DOCTYPE html>
<html>
<head>
<style>
  /* Theme 1: Blue */
  styled-card::part(container) {
    border: 2px solid #3b82f6;
    border-radius: 12px;
    max-width: 400px;
    margin: 15px;
    overflow: hidden;
    box-shadow: 0 4px 6px rgba(0,0,0,0.1);
  }

  styled-card::part(header) {
    background: #3b82f6;
    color: white;
    padding: 20px;
  }

  styled-card::part(title) {
    margin: 0;
    font-size: 20px;
  }

  styled-card::part(body) {
    padding: 20px;
  }

  styled-card::part(footer) {
    background: #f1f5f9;
    padding: 15px 20px;
    border-top: 2px solid #e2e8f0;
  }

  /* Theme 2: Dark */
  .dark-theme::part(container) {
    border-color: #1e293b;
    background: #1e293b;
    color: white;
  }

  .dark-theme::part(header) {
    background: #0f172a;
  }

  .dark-theme::part(body) {
    background: #1e293b;
  }

  .dark-theme::part(footer) {
    background: #0f172a;
    border-top-color: #334155;
  }

  /* Theme 3: Green */
  .success-theme::part(header) {
    background: #10b981;
  }

  .success-theme::part(container) {
    border-color: #10b981;
  }
</style>
</head>
<body>
<h2>Themed Cards with CSS Parts</h2>

<div style="display: flex; gap: 20px; flex-wrap: wrap;">
  <styled-card>
    <span slot="title">Blue Theme</span>
    <p slot="content">This card uses the default blue theme styling.</p>
    <button slot="action">Learn More</button>
  </styled-card>

  <styled-card class="dark-theme">
    <span slot="title">Dark Theme</span>
    <p slot="content">This card uses the dark theme styling.</p>
    <button slot="action" style="background: #3b82f6; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">Learn More</button>
  </styled-card>

  <styled-card class="success-theme">
    <span slot="title">Success Theme</span>
    <p slot="content">This card uses the success theme styling.</p>
    <button slot="action" style="background: #10b981; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">Learn More</button>
  </styled-card>
</div>

<script>
  class StyledCard extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });

      shadow.innerHTML = `
        <style>
          .container {
            background: white;
          }
        </style>

        <div class="container" part="container">
          <div part="header">
            <h3 part="title">
              <slot name="title">Card Title</slot>
            </h3>
          </div>
          <div part="body">
            <slot name="content">Card content goes here</slot>
          </div>
          <div part="footer">
            <slot name="action"></slot>
          </div>
        </div>
      `;
    }
  }

  customElements.define('styled-card', StyledCard);
</script>
</body>
</html>

Custom Input with Exposed Parts

<!DOCTYPE html>
<html>
<head>
<style>
  /* Style the input parts */
  custom-input::part(container) {
    margin: 20px;
    max-width: 400px;
  }

  custom-input::part(label) {
    display: block;
    font-weight: bold;
    margin-bottom: 8px;
    color: #1e293b;
  }

  custom-input::part(input) {
    width: 100%;
    padding: 12px;
    border: 2px solid #cbd5e1;
    border-radius: 8px;
    font-size: 16px;
    transition: border-color 0.2s;
  }

  custom-input::part(input):focus {
    outline: none;
    border-color: #3b82f6;
  }

  custom-input::part(error) {
    color: #ef4444;
    font-size: 13px;
    margin-top: 5px;
  }

  custom-input::part(hint) {
    color: #64748b;
    font-size: 13px;
    margin-top: 5px;
  }

  /* Dark theme */
  .dark-input::part(label) {
    color: white;
  }

  .dark-input::part(input) {
    background: #1e293b;
    color: white;
    border-color: #334155;
  }

  .dark-input::part(input):focus {
    border-color: #60a5fa;
  }
</style>
</head>
<body>
<h2>Styleable Form Inputs</h2>

<div style="background: white; padding: 20px;">
  <custom-input label="Email Address" hint="We'll never share your email"></custom-input>
  <custom-input label="Password" type="password" hint="Must be at least 8 characters"></custom-input>
</div>

<div style="background: #0f172a; padding: 20px; margin-top: 20px;">
  <custom-input class="dark-input" label="Username" hint="Choose a unique username"></custom-input>
  <custom-input class="dark-input" label="Full Name" hint="Enter your full name"></custom-input>
</div>

<script>
  class CustomInput extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });

      const label = this.getAttribute('label') || 'Input';
      const type = this.getAttribute('type') || 'text';
      const hint = this.getAttribute('hint') || '';

      shadow.innerHTML = `
        <div part="container">
          <label part="label">${label}</label>
          <input part="input" type="${type}" placeholder="${label}">
          <div part="hint">${hint}</div>
          <div part="error" style="display: none;"></div>
        </div>
      `;
    }
  }

  customElements.define('custom-input', CustomInput);
</script>
</body>
</html>

Result

Interactive code playground requires JavaScript. Here's the code:

<!DOCTYPE html>
<html>
<head>
<style>
  /* Style the input parts */
  custom-input::part(container) {
    margin: 20px;
    max-width: 400px;
  }

  custom-input::part(label) {
    display: block;
    font-weight: bold;
    margin-bottom: 8px;
    color: #1e293b;
  }

  custom-input::part(input) {
    width: 100%;
    padding: 12px;
    border: 2px solid #cbd5e1;
    border-radius: 8px;
    font-size: 16px;
    transition: border-color 0.2s;
  }

  custom-input::part(input):focus {
    outline: none;
    border-color: #3b82f6;
  }

  custom-input::part(error) {
    color: #ef4444;
    font-size: 13px;
    margin-top: 5px;
  }

  custom-input::part(hint) {
    color: #64748b;
    font-size: 13px;
    margin-top: 5px;
  }

  /* Dark theme */
  .dark-input::part(label) {
    color: white;
  }

  .dark-input::part(input) {
    background: #1e293b;
    color: white;
    border-color: #334155;
  }

  .dark-input::part(input):focus {
    border-color: #60a5fa;
  }
</style>
</head>
<body>
<h2>Styleable Form Inputs</h2>

<div style="background: white; padding: 20px;">
  <custom-input label="Email Address" hint="We'll never share your email"></custom-input>
  <custom-input label="Password" type="password" hint="Must be at least 8 characters"></custom-input>
</div>

<div style="background: #0f172a; padding: 20px; margin-top: 20px;">
  <custom-input class="dark-input" label="Username" hint="Choose a unique username"></custom-input>
  <custom-input class="dark-input" label="Full Name" hint="Enter your full name"></custom-input>
</div>

<script>
  class CustomInput extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });

      const label = this.getAttribute('label') || 'Input';
      const type = this.getAttribute('type') || 'text';
      const hint = this.getAttribute('hint') || '';

      shadow.innerHTML = `
        <div part="container">
          <label part="label">${label}</label>
          <input part="input" type="${type}" placeholder="${label}">
          <div part="hint">${hint}</div>
          <div part="error" style="display: none;"></div>
        </div>
      `;
    }
  }

  customElements.define('custom-input', CustomInput);
</script>
</body>
</html>

Multiple Parts on Same Element

<!DOCTYPE html>
<html>
<head>
<style>
  /* Style specific combinations of parts */
  status-badge::part(badge) {
    display: inline-block;
    padding: 6px 12px;
    border-radius: 16px;
    font-size: 13px;
    font-weight: 600;
    margin: 5px;
  }

  /* Status-specific styling */
  status-badge::part(success) {
    background: #dcfce7;
    color: #166534;
  }

  status-badge::part(warning) {
    background: #fef3c7;
    color: #92400e;
  }

  status-badge::part(error) {
    background: #fee;
    color: #b91c1c;
  }

  status-badge::part(info) {
    background: #dbeafe;
    color: #1e40af;
  }

  /* Style the icon part */
  status-badge::part(icon) {
    margin-right: 6px;
  }

  /* Style the text part */
  status-badge::part(text) {
    font-weight: 700;
  }
</style>
</head>
<body>
<h2>Status Badges with Multiple Parts</h2>

<div style="padding: 20px;">
  <status-badge status="success">Operation Successful</status-badge>
  <status-badge status="warning">Warning Message</status-badge>
  <status-badge status="error">Error Occurred</status-badge>
  <status-badge status="info">Information</status-badge>
</div>

<script>
  class StatusBadge extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });
      const status = this.getAttribute('status') || 'info';

      const icons = {
        success: '✓',
        warning: '⚠',
        error: '✗',
        info: 'ℹ'
      };

      shadow.innerHTML = `
        <span part="badge ${status}">
          <span part="icon ${status}-icon">${icons[status]}</span>
          <span part="text ${status}-text"><slot></slot></span>
        </span>
      `;
    }
  }

  customElements.define('status-badge', StatusBadge);
</script>
</body>
</html>

Result

Interactive code playground requires JavaScript. Here's the code:

<!DOCTYPE html>
<html>
<head>
<style>
  /* Style specific combinations of parts */
  status-badge::part(badge) {
    display: inline-block;
    padding: 6px 12px;
    border-radius: 16px;
    font-size: 13px;
    font-weight: 600;
    margin: 5px;
  }

  /* Status-specific styling */
  status-badge::part(success) {
    background: #dcfce7;
    color: #166534;
  }

  status-badge::part(warning) {
    background: #fef3c7;
    color: #92400e;
  }

  status-badge::part(error) {
    background: #fee;
    color: #b91c1c;
  }

  status-badge::part(info) {
    background: #dbeafe;
    color: #1e40af;
  }

  /* Style the icon part */
  status-badge::part(icon) {
    margin-right: 6px;
  }

  /* Style the text part */
  status-badge::part(text) {
    font-weight: 700;
  }
</style>
</head>
<body>
<h2>Status Badges with Multiple Parts</h2>

<div style="padding: 20px;">
  <status-badge status="success">Operation Successful</status-badge>
  <status-badge status="warning">Warning Message</status-badge>
  <status-badge status="error">Error Occurred</status-badge>
  <status-badge status="info">Information</status-badge>
</div>

<script>
  class StatusBadge extends HTMLElement {
    constructor() {
      super();
      const shadow = this.attachShadow({ mode: 'open' });
      const status = this.getAttribute('status') || 'info';

      const icons = {
        success: '✓',
        warning: '⚠',
        error: '✗',
        info: 'ℹ'
      };

      shadow.innerHTML = `
        <span part="badge ${status}">
          <span part="icon ${status}-icon">${icons[status]}</span>
          <span part="text ${status}-text"><slot></slot></span>
        </span>
      `;
    }
  }

  customElements.define('status-badge', StatusBadge);
</script>
</body>
</html>

How It Works

Exposing Parts

Inside shadow DOM, use part attribute:

class MyComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });

    shadow.innerHTML = `
      <div part="container">
        <button part="button">Click</button>
        <span part="label">Label</span>
      </div>
    `;
  }
}

Styling Parts

Outside, use ::part() pseudo-element:

my-component::part(container) {
  background: white;
  border: 2px solid #e2e8f0;
  border-radius: 8px;
}

my-component::part(button) {
  background: #3b82f6;
  color: white;
  padding: 10px 20px;
}

my-component::part(label) {
  color: #64748b;
}

Multiple Part Names

Elements can have multiple part names:

<!-- Inside shadow DOM -->
<button part="button primary">Primary Button</button>

<!-- Style either part -->
<style>
  my-component::part(button) { /* Styles */ }
  my-component::part(primary) { /* Styles */ }
</style>

Best Practices

1. Expose Logical Parts

// Good: Semantic, reusable part names
shadow.innerHTML = `
  <div part="container">
    <header part="header">
      <h2 part="title"></h2>
    </header>
    <main part="body"></main>
    <footer part="footer"></footer>
  </div>
`;

// Bad: Too granular or unclear
shadow.innerHTML = `
  <div part="div1">
    <div part="div2">
      <span part="span1"></span>
    </div>
  </div>
`;

2. Document Exposed Parts

/**
 * <my-button>
 *   Exposed parts:
 *   - button: The main button element
 *   - icon: Button icon (if present)
 *   - label: Button text label
 * </my-button>
 */
class MyButton extends HTMLElement { }

3. Use Consistent Naming

// Good: Consistent across components
part="header"
part="body"
part="footer"

// Bad: Inconsistent
part="top"
part="content"
part="bottom-section"

4. Don’t Over-Expose

// Good: Expose key styling points
shadow.innerHTML = `
  <div part="container">
    <button part="button">
      <slot></slot>
    </button>
  </div>
`;

// Bad: Every element exposed
shadow.innerHTML = `
  <div part="div">
    <span part="span1">
      <span part="span2">
        <button part="button">
          <span part="span3"></span>
        </button>
      </span>
    </span>
  </div>
`;

Limitations

Cannot Style Pseudo-Elements

/* ✗ Doesn't work */
my-component::part(button)::before {
  content: "»";
}

/* ✓ Workaround: Expose another part */
my-component::part(button-icon) {
  /* Style the icon part */
}

Cannot Combine with Element Selectors

/* ✗ Doesn't work */
my-component button::part(label) { }

/* ✓ Works */
my-component::part(label) { }

Cannot Access Nested Parts Directly

/* ✗ Doesn't work (parts inside parts) */
my-component::part(container)::part(button) { }

/* ✓ Workaround: Use exportparts on intermediate component */

JavaScript API

Checking Part Attribute

const element = shadowRoot.querySelector('[part]');
console.log(element.part); // DOMTokenList
console.log(element.part.contains('button')); // true/false

// Modify parts
element.part.add('active');
element.part.remove('disabled');
element.part.toggle('selected');

Common Patterns

Themeable Component

class ThemeCard extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });

    shadow.innerHTML = `
      <div part="card">
        <header part="header">
          <slot name="title"></slot>
        </header>
        <div part="body">
          <slot></slot>
        </div>
        <footer part="footer">
          <slot name="actions"></slot>
        </footer>
      </div>
    `;
  }
}

/* Light theme */
theme-card::part(card) {
  background: white;
  color: black;
}

/* Dark theme */
.dark theme-card::part(card) {
  background: #1e293b;
  color: white;
}

State-Based Parts

class ToggleButton extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    this.isOn = false;

    shadow.innerHTML = `
      <button part="button">
        <span part="label">Toggle</span>
      </button>
    `;

    shadow.querySelector('button').addEventListener('click', () => {
      this.isOn = !this.isOn;
      this.updateParts();
    });
  }

  updateParts() {
    const button = this.shadowRoot.querySelector('button');
    button.part = this.isOn ? 'button active' : 'button';
  }
}

Browser Support

Browser	Support
Chrome	73+
Firefox	72+
Safari	13.1+
Edge	79+

exportparts attribute - Forward parts from nested components
::part() CSS pseudo-element - Select exposed parts
Shadow DOM - Encapsulated DOM trees
slot attribute - Content projection

The part Attribute

The part Attribute

Syntax

Values

Examples

Basic Themeable Button

Styled Card Component

Custom Input with Exposed Parts

Multiple Parts on Same Element

How It Works

Exposing Parts

Styling Parts

Multiple Part Names

Best Practices

1. Expose Logical Parts

2. Document Exposed Parts

3. Use Consistent Naming

4. Don’t Over-Expose

Limitations

Cannot Style Pseudo-Elements

Cannot Combine with Element Selectors

Cannot Access Nested Parts Directly

JavaScript API

Checking Part Attribute

Common Patterns

Themeable Component

State-Based Parts

Browser Support

Related Concepts

Specifications

The `part` Attribute