Web Components and HTML Patterns in Bolt

Bolt isn't defined by the technology it uses — in fact, that's why we built it to be technology‑agnostic. Instead, Bolt is defined by the behaviors, accessibility, and UX guarantees it provides.

Web components are one way Bolt delivers those guarantees. HTML patterns are another. Understanding the difference between the two is less about visuals and more about how responsibility is distributed between the design system and the product team.

Once that distinction is clear, deciding which to use becomes much simpler.

At a high level:

• A web component is like a "black box" that encapsulates structure, styles, and behavior inside it.
  • Customization and integrations are limited by the APIs provided by the web component itself.
• An HTML pattern provides a structural blueprint for building semantic markup using pre-defined styles.
  • Inter-element behavior has to be wired up explicitly by the product team.

They often render the same UI; they just support different needs and workflows.

Bolt defines the specifications.
Components and patterns are just different ways to apply them.

Web components	HTML patterns
Drop‑in implementations Web components are designed to be ready‑to‑use. When you use one, you're opting into a set of guarantees that come pre‑assembled.	Clarity and control HTML patterns exist for a different reason. They provide control and flexibility when a packaged component isn't the right fit.
Built‑in behavior and state A Bolt web component already includes: - Interaction logic (open/close, toggle, validation, focus handling) - Internal state management - Event handling that works out of the box Keyboard interactions are accounted for. ARIA states update correctly. Common edge cases have already been handled. The result is something that is immediately functional, not just structurally correct.	Flexibility without abstraction An HTML pattern is: - Plain markup - Free of hidden logic - Unopinionated about lifecycle or state This makes it possible to tailor behavior to complex or non‑standard workflows—especially when integrating with existing systems or custom state management.
An accessibile foundation - Encode correct ARIA roles and relationships - Manage focus and keyboard navigation - Reduce the risk of accessibility regressions across products Accessibility is a foundational part of the component's spec, not something each team has to rebuild from scratch.	Transparency and debuggability - All behavior is explicit - There's no abstraction layer to work around - Debugging is straightforward This is especially valuable in performance‑sensitive contexts, advanced integrations, or legacy environments where web components aren't practical.
Consistency and stability across teams and products Because behavior lives inside the component: - Everyone gets the same interaction patterns - Fixes, improvements and updates to appearance and best practice behavior propagate everywhere - without re-implementation - Sticking to official web component configuration options makes it easy to follow migration guides or use automated upgrade tools This is how Bolt maintains consistency at scale—it behaves like a system rather than a collection of styles.	Longevity and portability HTML patterns: - Don't depend on frameworks or build systems - Continue to be useful even if implementations change They act as durable reference documentation, defining structure and semantics independently of any one technology choice.
Lower cognitive load for product teams Using a web component means fewer decisions to make. Teams can focus on how the component fits within their product rather than on the mechanics of getting it to work correctly. In most cases, this leads to faster implementation and fewer subtle issues.	Educational value Patterns also serve as teaching tools. They show how pieces fit together and why certain semantic relationships matter, making them useful for onboarding and documentation as well as implementation.

In practice, the decision usually comes down to responsibility and constraints.

Use a web component when…	Use an HTML pattern when…
You need a strong foundation for accessibility to start from. (Web components can't handle 100% of every specific accessibility need, but they do handle a lot of the boilerplate.)	You're integrating with third-party libraries or legacy systems that have limited or no compatibility with web components.
Consistency across products and teams matters.	You require full control over state and JavaScript.
You don't need to significantly alter behavior beyond supported options.	You're documenting or teaching Bolt usage, or need a durable reference.
You want a ready‑to‑use solution with minimal setup.	You need to expand on the implementation of a component (i.e., bespoke behaviors, layouts) AND you have the resources to review, test, and maintain for the lifespan of the application

Both approaches are valid. The key is choosing the one that aligns with your needs.

Yes. HTML patterns are implementation blueprints, not mockups. Web components are pre‑assembled implementations. Both are designed for engineers and supported by Bolt.

No. HTML patterns are part of Bolt. As long as semantics, behaviors, and accessibility align with Bolt guidance, you are still working within the system.

No. In the UX sense, this is a custom implementation, not custom design. If you follow Bolt's rules, you're still shipping Bolt UI, even without a packaged component.

• Web components are like pre-built products
• HTML patterns are like DIY kits

Neither is inherently more correct. They're simply optimized for different situations.

If you need a simple way to explain this to others:

Web components give you a ready‑to‑use, foundationally-accessible implementation.
HTML patterns give you the blueprint — so you can build exactly what you need.

Both are Bolt. The difference lies in how much is pre‑packaged and how much responsibility sits with the development team.