Snapshot 2026-10-31
HTML Next · Proposal

Declarative HTML Components Level 1

A markup-first component model that compiles to, and polyfills on, the web platform.

Unofficial Editor's Draft · Stage 0
Latest snapshot
31 October 2026
Reference implementation
html-next repo · polyfill & component bridge
Status
Unofficial Editor's Draft · Stage 0. Not a W3C or WHATWG deliverable.

Status of this document

An unofficial editor's draft for discussion at Stage 0. It is not a standard and does not represent the position of the W3C, the WHATWG, or any browser vendor.

This document specifies the component-authoring proposal in the HTML Next collection. It defines an authoring layer above the platform today, with the explicit aim that proven features are adopted into the platform through the normal standards process. Everything normative here currently constrains conforming tooling; that boundary would move as features graduate.

Abstract

Declarative HTML Components proposes a reliable, reactive component-authoring model for HTML. The platform gained a rendering engine, a networking stack, and a component mechanism, but never an application authoring model, so for fifteen years the primitives authors need most (reusable typed components, control flow, data sources, reactivity) were reinvented, incompatibly, in one JavaScript framework after another. This proposal expresses those primitives as markup, so the web gains a standard component layer that degrades to plain HTML and outlives any single framework.

In plain terms: you write components, control flow, and reactivity as HTML, and run the same file directly in the browser or compile it to React, Vue, or Svelte.

<!-- You write a component as markup -->
<x-button variant="solid">Save</x-button>

<!-- It becomes a real native button, in the light DOM -->
<button component="x-button">Save</button>

You author a component once, as literal browser-parseable HTML with an inert typed contract. A conforming implementation lowers it into idiomatic Vanilla DOM, React, Vue, and Svelte, or interprets the same source directly in Chromium, Firefox, and WebKit. One semantics, many backends.

Introduction & goals

The missing layer

The web platform kept advancing: fetch, Grid, ES modules, even Custom Elements and Shadow DOM. Yet HTML's own vocabulary for building applications barely grew. The primitives an app author reaches for every day were never added to markup, so the same wheel was reinvented, again and again and incompatibly, in userland. Ask HTML, natively, for any of these and the answer is still "load a framework":

Application needNative HTML answerWhat everyone does
Reusable typed component with a documented APINone (Custom Elements are untyped, imperative)React/Vue/Svelte component
Conditional & repeated markupNonev-if, {#each}, .map()
Declarative reactivityNonehooks, refs, runes, signals
Bind a control to stateNonecontrolled inputs, v-model
Declare a data dependencyNonefetch-in-effect, loaders, resources

Every cell in the right column is an incompatible language. Web Components addressed packaging and skipped the language problem: a place to put a component but no declarative way to write one.

Use the platform

The goal is to use the platform as much as possible. Each feature starts from real HTML and CSS patterns and from existing DOM interfaces: a component lowers to a native element, styles are scoped with CSS @scope, validity follows the Constraint Validation API, and events are DOM events. Where the platform has no pattern to draw on, the proposal adopts the shape that popular libraries have repeatedly and independently arrived at, such as conditional and repeated markup, two-way binding, and typed props.

The component model

A markup-first authoring language realized by two kinds of conforming implementation that must produce observably equivalent output:

The converter

An ahead-of-time compiler lowers HTML Next to idiomatic Vanilla DOM, React, Vue, Svelte, CSS, contracts, and docs: a multi-target converter in the spirit of Mitosis.

The polyfill

A browser runtime reads the same source, lowers it against the live DOM without Custom Elements or dynamic code, and subscribes to its declared dependency graph.

The proposal is both an authoring layer you can use today, through the converter and polyfill, and a set of platform features meant to graduate into HTML itself, feature by feature, the way Declarative Shadow DOM and invoker commands went from userland shim to shipped native syntax.

The proposal is purely additive markup. You add one feature to an ordinary HTML file, one tag at a time, and everything else stays exactly as it was. A plain HTML file already satisfies the language, so adoption starts from the files you have.

How the proposal versions

A number such as HTML Next 1.x names a version of the reference tools (see Stability comes from pinning). The proposal itself versions the way the platform does today, on three borrowed axes:

Levels, from CSS

CSS specifications advance by Level (Selectors 4, Color 5, Grid 2): each Level is a complete specification that extends the one before. Declarative HTML Components is one such specification, and this draft is Level 1. Its chapters are parts of one component model, so they advance together.

Stages, from proposals

HTML is a Living Standard; new features incubate as proposals (WICG explainers), and JavaScript proposals move through TC39 stages 0 to 4. This proposal is at Stage 0 today, and its maturity advances by stage.

A snapshot is the published version

A dated snapshot is the draft as published on that day, at its Level. It records what the proposal contains on that date; the working draft keeps moving.

The worked example is Web Components. The Level 1 chapters (components, templating, reactivity, scoping) provide a practical component authoring model today. The parts a compiler cannot supply, including native-element extension and deeper Shadow DOM integration, belong in later upstream platform proposals.

Stability comes from pinning

The proposal becomes stable when a standards venue adopts it; until then, the working draft can change on any day. Software built on it can be stable sooner, because a snapshot is fixed. A tool that implements one snapshot can promise to keep that snapshot's syntax working. A component library or an application built with that tool can then be stable for that tool's version, while the draft keeps moving.

Name the snapshot you implement

An implementation should state the snapshot it implements and the extensions it supports, for example Declarative HTML Components Level 1, Stage 0, snapshot of 25 September 2026, with no extensions. The reference tools publish how their versions map to snapshots, and what they promise within a version, in Versions and stability.

When the proposal goes to a standards venue, what it submits is a snapshot. From then on, that venue's process decides what changes and how the work is staged, and the snapshots published here remain as records.

What declarative components need

A complete component-authoring model needs reactivity, style scoping, and reliable native semantics. This proposal addresses each in its own chapter. Components lower to real native elements today; live reactivity and style scoping build on that; deeper platform integration remains upstream standards work.

1

Reactivity

A dependency graph you can read, type, and lower.
Why it's broken
  • HTML has no declarative reactivity, so every framework invented its own (VDOM diffing, proxies, compilers, signals), and they don't interoperate.
  • Reactivity is expressed in framework-specific JavaScript, not markup: it can't be inspected, typed once, or ported.
  • Most runtime approaches need dynamic code (new Function) or ship a diffing engine to every user.
This proposal's answer
  • Reactivity is a declarative dependency graph in markup: <state>, <computed>, <data>, and from:/bind: bindings over a small pure expression language.
  • The graph is statically analyzable: dependencies are read off the parsed expression before it runs.
  • One semantics, many backends: it lowers to React state, Vue refs, Svelte runes, or a signal-based browser runtime, CSP-clean.
2

Web Components

The platform's own component mechanism is broken in ways a compiler cannot repair. A polyfill routes around it today; the platform-level fix is an upstream proposal.
Why it's broken
  • No portable way to extend a native element: customized built-ins (is=) are formally opposed by WebKit, so extends HTMLButtonElement has no cross-browser path.2
  • The autonomous alternative, an <x-button> host, forfeits the native button's form submission, role, and focus, rebuilt by hand.
  • Form participation dies at the shadow boundary; it needs ElementInternals, which stabilized cross-browser only in 2023.6
  • Imperative ceremony, string-only props with no inspectable contract, and cross-boundary styling friction round it out.1
Polyfill today, platform change upstream
  • Templating and native lowering emit a real <button>, so native semantics stay the browser's.
  • The component is typed markup with a declarative contract and compiles to idiomatic React, Vue, and Svelte: portable across frameworks.
  • What a compiler cannot fix (WebKit's refusal of customized built-ins, form association across a boundary) is platform work for an upstream proposal.
  • Its likely shape: templating that opts into an extension of Declarative Shadow DOM, closing the styling and form gaps DSD left open.
3

Shadow DOM & scoping

Styles scoped to the component in the light DOM, with isolation available when you choose it.
Why it's broken
  • Shadow DOM gives all-or-nothing encapsulation. Styling across the boundary is painful (::part, ::slotted); global theming and shared styles fight it.
  • Declarative Shadow DOM and its SSR story arrived years late and remain awkward.
  • Forms, focus, and accessibility relationships behave surprisingly across the boundary.
  • Most authors want scoping, not isolation, and are forced to take both.
This proposal's answer
  • A component's styles are scoped to it by default: its <style> affects only its own markup, in the light DOM, through the scoping the browser already offers with CSS @scope. Encapsulation and isolation are separate choices.
  • Degrades to plain CSS in the light DOM: theming, cascade, and shared design tokens keep working.
  • Real isolation is an opt-in target capability.
  • An upstream proposal takes the isolation case further with an extension of Declarative Shadow DOM that fixes DSD's styling and form-participation gaps.

The record: Web Components in practice

Whether Web Components failed by design or only because they were never fully leveraged does not matter to an author choosing a component model today. In their shipped form they did not become the web's component layer, and the clearest evidence is the ecosystem's own behavior.

Champions retreated The flagship "components will replace frameworks" project was wound down.

Google's Polymer entered maintenance mode in 2018 and was superseded by Lit (a thin rendering helper) because raw custom-element ergonomics were not enough on their own.8

Framework authors opted out The people who build component models did not build them on this one.

The creator of Svelte set out in 2019 why he does not use Web Components: Shadow DOM forces CSS into JavaScript; the property/attribute split forces boilerplate; slotted content renders eagerly; the registry is one global namespace; and the DOM is "an awkward interface for building interactive applications."1 React, Vue, Svelte, and Solid each built their own model instead. HTML Next answers the eager-slot complaint directly: a consumer's <template slot> renders only while the slot that receives it renders, so content that slot does not render is never created, loaded, or set up (content that renders on demand).

The extension mechanism is blocked There is no cross-browser way to extend a native element.

Customized built-in elements ship in Chromium and Firefox, but WebKit's formal standards position is to oppose them and not implement them.23 The only spec-sanctioned route to reusing native semantics has no portable path.

Interop lagged a decade The largest UI library could not talk to them properly until 2024.

For most of the feature's life React could not pass an object or array to a custom element, nor listen to its events; the gap was tracked on Custom Elements Everywhere. Full support arrived only in React 19, December 2024, more than a decade after custom elements were proposed.45

Forms and SSR arrived late The basics took ten years to stabilize.

Form participation via ElementInternals stabilized cross-browser only with Safari 16.4 (March 2023); Declarative Shadow DOM reached Safari in 16.4 and Firefox in 123 (2024).67

Architecture

Three kinds of element

The proposal keeps three layers distinct: authoring syntax, generated output, and the runtime or compiler that connects them.

Control-flow directives$each $if $match
Component elements<x-button>
Output elements<button> <input>

Conforming implementations

Declarative HTML Components is a language specification: an implementation is a converter or a polyfill. Its governing conformance contract is observable equivalence: the same native DOM, state, events, accessibility, and errors for the same source.

Declarative component source→converter→Vanilla / React / Vue / Svelte + CSS + docs
Specification and implementation

The Next Web Working Group publishes the proposal and this site. The html-next implementation repository contains the current polyfill and converter. As more proposals gain implementations, each will have its own package over shared infrastructure.

Static output is the baseline

Progressive enhancement runs the other way from a hypermedia library: in htmx the server round-trip is the baseline and script enhances it; in HTML Next the rendered HTML is the baseline and the browser enhances it. A server-rendered page delivers its initial content as ordinary HTML that displays, is accessible, and is indexable with no JavaScript.

How far past that first render a no-JavaScript page reaches depends on the kind of reactivity:

  • State that maps to a native primitive (a toggle to <details> or popover, selection to :checked, validity to constraint validation, relational reactivity to :has()) lowers to HTML and CSS and keeps working with no script.
  • Genuinely dynamic reactivity (data fetches, values computed over live input, lists over changing data) needs the runtime, or a server-round-trip fallback that is still open.

So the guarantee is a no-JS render, and a no-JS application exactly as far as the reactivity has a native lowering.

Conformance & Levels

Level 1 is the whole component language across these chapters, including templating, live reactive updates, external composition, and the JavaScript layer; the optional extensions sit beside it. A Level describes the specification's scope; each tool reports its own implementation coverage. The draft remains at Stage 0, and implementations should identify the snapshot they support, as described in How the proposal versions.

Keywords follow RFC 2119, scoped to conforming implementations. A tool must emit an explicit unsupported-feature diagnostic, never silent literal fallback, for any construct it does not implement.

AreaLevel 1 contract
ComponentsTyped native-root components; default, named, fallback, and scoped slots; explicit polymorphic roots; external composition with <template src> and <portal>. See Components & Composition.
TargetsEquivalent Vanilla DOM, React, Vue, and Svelte output, with CSS and API documentation. See Targets & Equivalence.
Browser runtimeInitial lowering and live updates to the native DOM from the declared dependency graph, without Custom Elements or eval(). See Reactivity & Data.
Templating$each, $if, $match, $with, content directives, and {expression} text, with reactive bindings and keyed iteration. See Templating.
ReactivityMutable <state>, read-only <computed>, reactive <data> resources, change propagation, and connection-owned observation. See Reactivity & Data.
Rendered formServer-rendered native HTML and the records needed to recover component instances during hydration; remaining recovery questions are identified in Rendered Form & Hydration.
Forms and validationNative form ownership and submission; declared types and constraints participate in validity. HTML Forms defines expanded methods and composable submission scopes as an independent proposal.
TypesScalar types including keyword, integer, URLs, dates, and CSS values; structured lists and objects; value constraints and selected types. See Type System.
Style scopingComponent-scoped CSS in the light DOM. See Style Scoping.
JavaScript layerComponent modules and controllers through host, requests, and the component registry. See The JavaScript Layer.

Native-element extension and deeper Declarative Shadow DOM integration are upstream platform work. Optional extensions are listed separately below.

Extensions

An extension is an optional part of the language that sits outside every Level. Each one has a one-word name, so that tools and documentation can say exactly which extensions they support, and each moves through the proposal's own stages: Proposal (written down, not yet implemented), Incubation (implemented in the reference tools, still free to change), and finally adoption into a Level, or withdrawal.

An implementation may omit any extension. One that does must report an unsupported-extension diagnostic that names the extension when it meets that syntax, under the same rule as any construct it does not implement; each extension states what output, if any, such an implementation may still produce.

ExtensionAddsChapterStage
transitions$transition, $transition-nameTemplatingIncubation

A future exploration is different: it sketches a possible change to a Level, has no name, and no tool implements it.

Adoption

A spec convinces no one; four things do, in order.

1 · It runs today

Author one component; compile it to the framework you already ship, and polyfill it in the browser with no build. Adoption risk is one file.

2 · It deletes a problem

Each fix is a grievance a developer already has: reactivity lock-in, Custom Element ceremony, Shadow DOM pain.

3 · It's just HTML

No new mental-model tax: it reads like markup, survives the parser, and works under CSP. A component invocation even degrades to its inline children before any runtime runs.

4 · A demo and a name

One jaw-drop demo (one file → five targets + live browser) and a name that promises the next HTML.

Governance & the working group

The Next Web Working Group exists today as a GitHub organization. The path to a recognized standards venue, cheapest rung first:

  1. The org is the specs and the site. Publishes standards; ships no tooling.
  2. A separate implementation repository, html-next, organized into proposal-specific packages as implementations are added.
  3. An explicit stage process, proposal → incubation → Level N, modeled on TC39 stages and WHATWG workstreams.
  4. A Community Group listing for legitimacy without W3C membership.
  5. Upstream the wins. A mature feature's endgame is a proposal into WHATWG/CSSWG/TC39.

Open questions

Genuine design questions, still open:

AreaQuestion
Rendered formRecovering explicit prop inputs and logical owners through server-rendered portals; a shared range grammar for structural anchors; consumer class and style origin. See Rendered Form & Hydration.
TypesParsing values when an untagged union admits more than one base type. See Type System.
BindingsWhether computed values should also provide a writable binding contract. See Bindings & Events.
Document headCrawler-specific robots names as page-wide head entries; reading the status of an authored script that settled before the runtime looked.
Prior art, credited

Shopify Liquid (constrained template language, filter pipelines), Squarespace JSON-T (data-context-first templating), Vue & Svelte (markup-first components, scoped styles, browser-safe binding syntax), Mitosis (one source → many framework targets), and XSLT (declarative tree transformation) are inputs and evidence; none is adopted as the default answer.

References

Informative. Retrieved September 2026; standards positions and browser versions as published.

  1. Rich Harris. "Why I don't use web components." DEV, 20 June 2019. dev.to/richharris/why-i-don-t-use-web-components-2cia
  2. WebKit. Standards position on customized built-in elements: oppose. Issue #97, 2022. github.com/WebKit/standards-positions/issues/97
  3. WebKit Bugzilla 182671. "Implementation (or not) of customized builtins." bugs.webkit.org/show_bug.cgi?id=182671
  4. Custom Elements Everywhere. Framework interoperability tests. custom-elements-everywhere.com
  5. React 19. Full custom-elements support, December 2024. react.dev/blog/2024/12/05/react-19
  6. WebKit. "ElementInternals and Form-Associated Custom Elements" (Safari 16.4, 2023). webkit.org/blog/13711
  7. WebKit. "Declarative Shadow DOM" (Safari 16.4; Firefox 123, 2024). webkit.org/blog/13851
  8. Lit. "Lit for Polymer users": Polymer superseded by Lit; in maintenance since 2018. lit.dev/articles/lit-for-polymer-users

Declarative HTML Components Level 1. Unofficial Editor's Draft · Stage 0. Published in the HTML Next collection by the Next Web Working Group; not a W3C or WHATWG deliverable. Version history.