Web Components docs

[trusktr]

We have a docs-and-guides channel in the WCCG discord: https://discord.gg/PZH8ucFHp2

It'll be nice to coordinate on web docs. The WCCG started a docs site at https://webcomponents.guide.

[Elchi3]

Hey @trusktr! Thanks for filing this issue! The Docs CG just started its work yesterday! We are wondering if we should talk about Web Components in our next Community Group call. Would you be up for that? We're meeting every 2nd Tuesday, at 5pm CEST. I'm going to sent out an invite for May 6 soon.

We had a few questions:

• Do you have an updating/maintenance plan for the site you've shared?
• What do you think about the docs that live on MDN? https://developer.mozilla.org/en-US/docs/Web/API/Web_components
• Do you know what needs web developers have when it comes to Web Components and how better docs could be helpful to them?
• There is https://2024.stateofhtml.com/en-US/features/web_components/ with some insights. Should we analyze this some more?
• Do you want to invite more people from the WCCG to have a conversation with us?

Looking forward to chat about Web Component docs either here or in the call!

[Elchi3]

In preparation for the W3C Docs CG call on Web Components, I took a look at the survey responses from the 2024 State of HTML survey:

Some survey free form responses specifically on the quality of WC docs:

• Hard to find documentation on making actual web components rather than react
• Lack of good manuals, tutorials, best practices and patterns
• Lack of practical resources, either chunks of references or badly written articles
• no documentation on lifecycle hooks apart from the spec
• Native web components technologies have bad documentation
• Not a lot of examples and documentation around
• Lack of a good introductory tutorial on web components. The existing tutorials all seem to be geared towards people coming from other JS frameworks, but not for someone starting with html

From other free form responses you can derive unanswered questions that web developers have. Possibly a starting point to check in current docs if are helpful to give answers or guidance at all.

• How to make shadow dom elements styleable?
• How to let in styles into the shadow dom? / How to share styles?
• How are you meant to use declarative shadow DOM without repeating the markup? / How to avoid so much boilerplate code?
• When to use Shadow Dom and when not?
• Accessibility of items in the shadow DOM?
• The shadow DOM is extremely tough to set up / too much complexity
• How to communicate data between document and shadow DOM?
• How to install WC's/make them available?

[Elchi3]

@tayloregivens gave a talk on Web Components: https://www.youtube.com/watch?v=dEFfqqJWLwQ. It provided me a great overview into current WC discussions.

Some quotes I found interesting and that maybe hint at how people (don't) adopt WC's currently.

• "There is no marketing team for WC. Enterprises are using them and it's quietly taking over because it is a useful feature but you kinda need specialists and well-resourced teams to pick it apart and figure out how to use it because it's more of a low-level tool. For the average developer, they use it using libraries such as lit or or fast or they might be using it in React if it is implemented under the hood. But most commonly we see it being used on the enterprise scale by more well-resourced teams."

• "Vanilla web components are pretty difficult to use by themselves"

• "We win and move things forward by shipping and working more closely with WC libraries"

• @atopal asked: "How we can see more adoption of WCs?" and Taylore said: "I had to do a lot of research for this talk to really understand where WC's are at." [...] "Find someone in enterprise teams to talk about WCs, but for hobbyist who are using it on a smaller scale, its harder for them to have access to resources and knowledge."

So, this hints that more docs are needed to get the hang of WCs and also that frameworks play a major role here.

[Elchi3]

Brief look into the current content outlines we seem to have. It's not a lot, so the needs expressed above are probably not addressed by the current state of the docs on neither MDN or webcomponents.guide:

MDN

(kept relatively up-to-date)

• Overview
  • https://developer.mozilla.org/en-US/docs/Web/API/Web_components
• Reference
  • Probably more or less complete.
• Guides:
  • Custom elements
  • Shadow DOM
  • Templates and slots
• How-tos
  • None
• Tutorials
  • None

webcomponents.guide

(last updated in 2023?)

• Overview
  • https://webcomponents.guide
• Reference
  • None
• Guides
  • Defining a component
  • Autonomous vs Customized Elements
  • Naming your components
  • Initializing your component
  • Rendering
  • Styling
• How-tos
  • Using Cancellation Signals
• Tutorials
  • Mastodon toot embed

[justinfagnani]

@Elchi3 a few years ago we tried to start a docs-and-guides effort in the WCCG. We came up with this content outline to work from: https://github.com/webcomponents-cg/docs-and-guides/blob/main/plan/outline.md

[Elchi3]

Yesterday's Docs CG call was all about Web Components. Here are the meeting notes: Notes from yesterday's call: https://github.com/w3c-cg/webdocs/blob/main/meetings/2025-05-06.md

[wbamberg]

Looking at the WC docs on MDN, and thinking of the context of today's call, I would say that the MDN docs are very much targeted at "implementing your own WC from scratch" and don't really acknowledge the existence of libraries, or what someone might need to know who is using a library.

So for instance the main guide is https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements, which is mostly about implementing a custom element.

I think it would be worth looking at these docs from the perspective of two audiences: people writing custom elements from scratch, and people using a library like Lit. And making this distinction explicit in the docs: essentially providing two separate paths for people.

We could also review the Lit docs to understand where the points are that they want to reach out into library-agnostic docs.

• As we said in the call, shadow DOM concepts is one of these. There is an MDN guide to shadow DOM (https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) but we might want to reorganize it - in particular it combines how-to (how to create a shadow DOM) with conceptual explanation (what the implications of shadow DOM are for things like encapsulation).

• Another one is probably lifecycle. MDN does talk about lifecycle callbacks, but the docs are kind of embedded in the main "using a custom element" guide (https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks, https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes) - it would probably be worth splitting this out into a separate page.

• Another one is probably some of the stuff on events, like https://lit.dev/docs/components/events/#shadowdom, which doesn't exist anywhere in the MDN WC docs.

Another separate issue is that there's no guide material on MDN about ElementInternals.

[tidoust]

Another angle highlighted in yesterday's call was that guides are missing for "using a web component" in the sense of "integrating a web component coming from a third party within a page": how to define slots when you instantiate the component, how to use :defined or :slotted, and how to style the component in general, how to register for events that the element may fire, etc.

That part of the guide would be independent from the library that might have been used to create the web component.

[justinfagnani]

I think it would be worth looking at these docs from the perspective of two audiences: people writing custom elements from scratch, and people using a library like Lit. And making this distinction explicit in the docs: essentially providing two separate paths for people.

From the Lit team's point of view on this, I think it's worthwhile examining the docs from these two perspectives, but I'm less sure about two actually different paths. At least in Lit's case there isn't anything in the vanilla web components reference or concepts that we wouldn't want developers to know. For example, while Lit does implement some of the standard lifecycle callbacks for the developer, the developer should ideally still understand them and can still override and implement them themselves.

One type of thing that could have some separate vanilla vs library guidance is best practices that libraries take care of for you, like using templates, batching DOM updates, implementing reactive class properties, and reflecting attributes. These are things have a little bit of opinion to them, and need glue code and patterns just above the most basic usage of the raw APIs.

I do think that two paths should exist for writing vs using custom elements, especially so that component authors have common high quality docs to point their users to for fundamental platform behavior.