Common way to declare configurable styles in web components

[alizedebray]

Option 1: Define CSS custom properties on the host

post-component styles:

:host {
  --post-component-size: 1rem;
  height: var(--post-component-size);
}

Usage in other components:

post-other-component {
  post-component {
    --post-component-size: 2rem;
  }
}

Option 2: Use a var() with a fallback

post-component styles:

:host {
  height: var(--post-component-size, 1rem);
}

Usage in other components:

post-other-component {
  --post-component-size: 2rem;
}

Option 3: Use parts

post-component renderer:

render() {
  return (
    <Host>
      <div part="component-div"></div>
    </Host>
  );
}

post-component styles:

[part="component-div"] {
  height: 1rem;
}

Usage in other components:

post-other-component {
  post-component:part(component-div) {
    height: 2rem;
  }
}

---

	Advantages	Inconvenients
Host vars	Encapsulated vars scoped on component, safer from global leaks	Less flexible override scope, more verbose selectors needed
var() with fallback	Most flexible and easy for consumers, cascade works naturally	Less encapsulated, global vars can collide, fallback hides errors
parts	Most precise styling control, strong encapsulation on exposed parts	Requires manual exposure, fragile if internals change, maybe too flexible?

Please add your comments or vote by reacting to the discussion with:

• 👍 for Option 1
• 🎉 for Option 2
• 🚀 for Option 3
• 👀 + 👍/🎉 to mix parts and you preferred var() option

[oliverschuerch]

IMO option 1 & 3 may be harder to override, but they are well scoped, while version to is leaky and could cause unwanted side effects and also produce naming conflicts.

I'm voting for
Option 1 👍🏼 => if we want to give access to a specific property
AND
Option 3 🚀 => if we want to give full access to a specific element

[gfellerph]

Option 1 is a more complicated way of writing option 2. Otherwise I'd agree with Oli. Sometimes it's handy to have access to a whole element (e.g. dropdown arrow to be able to set size, background, position, animation etc. in one go), sometimes a simple property tweaking is enough.

Documenting the two options appropriately is key.

[alizedebray]

Option 1 is a more complicated way of writing option 2.

Almost, option 1 is better encapsulated because you must specifically target the component to override the variable whereas with option 2 the variable is inherited.

[gfellerph]

I think the inheritance would make it easier to write overrides for a project because they could do

:root {
  --button-background: red;
  --some-component-border-radius: 100000px;
  /* ... */
}

instead of

.btn {
  --button-background: red;
}

.some-other-component {
  --some-component-border-radius: 100000px;
}

[alizedebray]

I agree that CSS variables and parts can be useful for different situations, and both could help us. But they also let users change our components, which might cause inconsistencies with our design language. So, I think it’s important to clearly state how and when to use them, depending on what we want to allow or prevent.

For example, we recently got a message in our support channel where a user wanted to change the accordion styles using a CSS part that was originally made to simplify internal styling: https://teams.microsoft.com/l/message/19:[email protected]/1752758349749?tenantId=3ae7c479-0cf1-47f4-8f84-929f364eff67&groupId=123c7c9e-052a-40e6-98d3-6cc6d46bad0a&parentMessageId=1752736838706&teamName=Design%20System&channelName=%F0%9F%9A%91%20Support&createdTime=1752758349749