Declaratieve gedeeltelijke updates

Gepubliceerd: 19 mei 2026, laatst geüpdatet: 8 september 2026

Het web is al lang niet meer het statische, op documenten gebaseerde medium dat het ooit was. Iedereen gebruikt moderne, uitgebreide web-apps om verschillende redenen, van communiceren, aankopen doen en uitgebreide content consumeren tot ons complexe leven beheren.

Ondanks alle ontwikkelingen wordt HTML nog steeds op volgorde van boven naar beneden geleverd, zonder rekening te houden met wanneer content klaar is of wanneer de gebruiker deze gebruikt. Met CSS kun je de volgorde van content wijzigen, maar dit heeft vaak aanzienlijke gevolgen voor de toegankelijkheid. Met JavaScript kun je de DOM manipuleren via verschillende API's om hier enigszins aan te ontsnappen, maar die vereisen vaak een uitgebreide syntaxis of de constructie van DOM-boomstructuren om in HTML te pluggen.

Prestaties zijn ongelooflijk belangrijk voor het web, gezien de client-server-aard van het medium. Er worden vaak suboptimale keuzes gemaakt om deze volgorde van HTML te omzeilen, wat de prestaties vertraagt. Dit omvat wachten tot de hele pagina klaar is of een zwaar framework gebruiken om componenten asynchroon te leveren. De populariteit van JavaScript-frameworks toont aan dat webontwikkelaars de voorkeur geven aan een op componenten gebaseerd model in plaats van het rigide documentmodel van de oorsprong van het web.

Het Chrome-team heeft dit probleem overwogen en heeft nieuwe toevoegingen aan het webplatform ontwikkeld onder de naam Declarative Partial Updates.

Met de eerste 2 nieuwe sets API's kun je HTML makkelijker op een minder lineaire manier leveren, of dat nu niet op volgorde is in het HTML-document zelf of via makkelijkere manieren om HTML dynamisch in bestaande documenten in te voegen met nieuwe JavaScript-API's. Er zijn ook polyfills beschikbaar waarmee je deze nieuwe API's meteen kunt gebruiken, zelfs in browsers die ze nog niet ondersteunen.

Streaming in onjuiste volgorde

Browser Support

  • Chrome: 150.
  • Edge: 150.
  • Firefox: not supported.
  • Safari: not supported.

Source

De eerste set wijzigingen bestaat uit nieuwe API's voor streaming die niet op volgorde is met tijdelijke aanduidingen voor verwerkingsinstructies en het HTML-element <template> met het kenmerk for. Voorbeeld:

<div>
  <?marker name="placeholder">
</div>

...

<template for="placeholder">
  Here is some <em>HTML content</em>!
</template>

Verwerkingsinstructies bestaan al heel lang in XML, maar worden in HTML behandeld als reacties en genegeerd. Deze nieuwe API verandert dat en brengt verwerkingsinstructies naar HTML. Als de browser bijvoorbeeld de verwerkingsinstructie <?marker name="placeholder"> ziet, doet deze niet meteen iets (net als eerder), maar kan er later naar worden verwezen.

Het <template>-element met het for-kenmerk zoekt de bijbehorende verwerkingsinstructies met een name-kenmerk op en vervangt de content. In dit geval wordt het DOM na het parseren als volgt (enkele verschillen in witruimte genegeerd):

<div>
  Here is some <em>HTML content</em>!
</div>

Naast het kenmerk <?marker> voor vervangingen zijn er ook de bereikmarkeringen <?start> en <?end> waarmee tijdelijke tijdelijke content kan worden getoond voordat de template wordt verwerkt:

<div>
  <?start name="another-placeholder">
  Loading…
  <?end>
</div>

...

<template for="another-placeholder">
  Here is some <em>HTML content</em>!
</template>

In dit geval wordt een Loading…-tekenreeks getoond totdat de <template> wordt gezien. Daarna wordt deze vervangen door de nieuwe content.

Je kunt ook verwerkingsinstructies opnemen in templates om meerdere updates toe te staan:

<ul id="results">
  <?start name="results">
  Loading…
  <?end>
</ul>

...

<template for="results">
  <li>Result One</li>
  <?marker name="results">
</template>

...

<template for="results">
  <li>Result Two</li>
  <?marker name="results">
</template>

...

Dit leidt tot de volgende HTML nadat deze is geparseerd en verwerkt:

<ul id="results">
  <li>Result One</li>
  <li>Result Two</li>
  <?marker name="results">
</ul>

Met de laatste verwerkingsinstructie aan het einde, voor het geval er later nog meer <template for="results">-placeholders aan het document worden toegevoegd.

Waarom verwerkingsinstructies in plaats van standaard HTML-elementen?

Dit is een veelgestelde vraag voor mensen die deze API voor het eerst gebruiken, met suggesties om <slot> of zelfs <template>-elementen zelf te gebruiken. Een eerste versie van dit voorstel werkte met standaard HTML-elementen, maar de verwerkingsinstructies werden gewijzigd toen het ontwerp werd herhaald. Met verwerkingsinstructies kan patching plaatsvinden zonder dat dit invloed heeft op het DOM. Hierdoor kan dit worden gebruikt in de <head>, bijvoorbeeld voor <title>-updates, of zelfs in andere elementen zoals <table> (bijvoorbeeld om optionele extra rijen toe te voegen).

Hoewel de syntaxis voor veel webontwikkelaars onbekend is, bieden verwerkingsinstructies veel meer flexibiliteit met minder kans op problemen met compatibiliteit met eerdere versies. Ze worden al gebruikt in XML en maken dankzij dit voorstel nu deel uit van de HTML-standaard.

Demo

In deze video wordt een eenvoudige fotoalbum-app geïmplementeerd met streaming HTML:

Demo van een fotoalbum geïmplementeerd met out-of-order streaming (bron)

Zowel de status als de foto's worden na de eerste indeling naar de HTML gestreamd.

Toepassingen

Er zijn veel toepassingen voor deze HTML-patching die niet op volgorde is, in combinatie met streaming HTML:

  • Eilandarchitectuur. Een veelvoorkomend patroon dat populair is geworden door frameworks zoals Astro is de eilandarchitectuur, waarbij componenten onafhankelijk van elkaar worden gehydrateerd bovenop statische HTML. Met de <template for> API kan statische content op een vergelijkbare manier rechtstreeks in HTML worden verwerkt. JavaScript-frameworks kunnen dit ook gebruiken voor interactievere eilanden of om componenten te verwerken.
  • Lever content aan zodra deze klaar is. Dankzij deze eilandarchitectuur kan content worden gestreamd zodra deze klaar is, in plaats van dat deze wordt tegengehouden voor content die extra verwerking vereist, zoals een databasezoekopdracht. Hoewel veel platforms HTML-streaming toestaan, betekent de volgorde van HTML dat content vaak wordt tegengehouden of dat er complexe JavaScript DOM-manipulaties worden gebruikt. Nu kun je de statische content leveren terwijl je wacht en daarna duurdere en dynamische content invoegen aan het einde van de HTML-stream.
  • HTML kan worden geleverd in de optimale volgorde voor de laadprestaties van de pagina. Je kunt de volgorde zelfs wijzigen als de bestelling al klaar is. Megamenu's zijn bijvoorbeeld een veelgebruikte navigatiefunctie die veel HTML bevat die de gebruiker pas ziet als de pagina interactief wordt. Dit grote stuk HTML kan later in het HTML-document worden geleverd om prioriteit te geven aan belangrijkere HTML die nodig is voor het laden van de eerste pagina. Volgorde is geen barrière meer met HTML.

Dit zijn maar een paar use cases en we zijn benieuwd waarvoor ontwikkelaars deze nieuwe API nog meer gaan gebruiken.

Beperkingen en subtiliteiten

De API bevat een aantal beperkingen en subtiliteiten waar u rekening mee moet houden:

  • <template for> kan verwerkingsinstructies alleen updaten binnen hetzelfde bovenliggende element om veiligheidsredenen. Als je <template for> rechtstreeks aan het element <body> toevoegt, krijgt het toegang tot het hele document (inclusief de <head>).
  • De verwerkingsinstructie <?end> is optioneel. Als deze ontbreekt, wordt de content tussen het element <?start> en het einde van het element dat deze bevat, vervangen.
  • Als je verwerkingsinstructies verplaatst nadat een <template for> is begonnen met streamen, kan dit ook onverwachte gevolgen hebben, waarbij de nieuwe content naar de oude locatie blijft streamen.
  • Als je <template for> dynamisch invoegt met een methode zoals setHTML of de property innerHTML, is de 'parent' van de template bij het parseren een tussenliggend documentfragment. Dit betekent dat als je HTML invoegt met deze methoden, de bestaande DOM niet kan worden gewijzigd en de patching 'in place' in het fragment plaatsvindt. Als je streamt met methoden zoals streamHTMLUnsafe (wordt binnenkort behandeld), is er geen tussenliggend fragment, zodat de templates bestaande content kunnen vervangen.

Standardization status

Het kenmerk <template for> maakt deel uit van de HTML-standaard, maar wordt nog niet in alle browsers ondersteund.

Mogelijke toekomstige toevoegingen

Enkele mogelijke toekomstige toevoegingen die worden overwogen, zijn:

  • Clientzijde omvat. Bijvoorbeeld <template for="footer" src="/partials/footer.html"> of zelfs zonder patching <template src="/partials/footer.html">. Ga naar de uitleg voor meer informatie. Deze functie is beschikbaar achter de markering chrome://flags/#enable-experimental-web-platform-features.
  • Voorkomen dat content die niet verandert, wordt overschreven. Dit kan worden bereikt met een contentrevisienummer of versiebeheer. Zo kan de status worden behouden tussen routewijzigingen of andere updates in plaats van dat de content wordt gereset.
  • Opschonen tijdens het patchen. Bijvoorbeeld <template for=icon safe><svg id="from-untrusted-source">...</svg></template>

Polyfill

Het Chrome-team heeft een template-for-polyfill uitgebracht die beschikbaar is op npm, zodat sites deze nieuwe functionaliteit meteen kunnen gebruiken, zelfs voordat deze in andere browsers beschikbaar is.

Er zijn enkele beperkingen omdat de HTML-parsers van de browser niet rechtstreeks kunnen worden geüpdatet, maar de meest voorkomende use cases worden gedekt. Sites moeten nog steeds testen in andere browsers.

Vernieuwde methoden voor HTML-invoeging en streaming

Niet alle content kan als HTML worden geleverd. Een tweede deel van het werk dat Chrome op dit gebied heeft gedaan, is bedoeld om het makkelijker te maken content te updaten met JavaScript.

Er zijn al meerdere manieren om HTML dynamisch in een bestaand document te injecteren met JavaScript:

  • setHTML
  • setHTMLUnsafe
  • innerHTML en outerHTML
  • createContextualFragment
  • insertAdjacentHTML

Ze werken allemaal op een net iets andere manier, met subtiele verschillen waar ontwikkelaars misschien niet altijd rekening mee houden:

  • Wordt de nieuwe content overschreven of toegevoegd?
  • Wordt potentieel gevaarlijke HTML opgeschoond, bijvoorbeeld door <script>-tags te escapen?
  • Zo niet, moet <script> dan worden uitgevoerd?
  • Hoe werken ze met Trusted Types?

Weinig ontwikkelaars kunnen die API's eerlijk bekijken en die vragen voor elk van hen met vertrouwen beantwoorden.

Een grote beperking is dat ze alleen kunnen worden gebruikt voor een complete set HTML die van tevoren bekend is, terwijl er verzoeken zijn om HTML te streamen. In de praktijk betekent dit dat u de hele content moet downloaden voordat u deze invoegt, terwijl een van de sterke punten van HTML juist is dat u content meteen kunt streamen. Je kunt dit op een beperkte manier omzeilen door payloads op te splitsen of verouderde methoden zoals document.write te gebruiken, maar die brengen hun eigen problemen met zich mee.

Een nieuwe set statische en streaming-API's

Browser Support

  • Chrome: behind a flag.
  • Edge: behind a flag.
  • Firefox: not supported.
  • Safari: not supported.

Chrome heeft gewerkt aan een pakket nieuwe API's en extensies voor de bestaande setHTML en setHTMLUnsafe die dit opschonen en streamingfunctionaliteit introduceren.

Deze zijn klaar voor ontwikkelaarstests vanaf Chrome 148 met de vlag chrome://flags/#enable-experimental-web-platform-features en de lancering staat gepland voor Chrome 155.

Er zijn methoden om content in te stellen of te vervangen, en methoden om content vóór of na bestaande HTML in te voegen. Elke methode heeft een stream-equivalent:

Actie Statisch Streaming
De HTML-content van het element instellen setHTML(html, options); streamHTML(options);
Het hele element vervangen door deze HTML replaceWithHTML(html, options); streamReplaceWithHTML(options);
De HTML toevoegen vóór het element beforeHTML(html, options); streamBeforeHTML(options);
De HTML toevoegen als het eerste onderliggende element van het element prependHTML(html, options); streamPrependHTML(options);
De HTML toevoegen als het laatste onderliggende element van het element appendHTML(html, options); streamAppendHTML(options);
De HTML toevoegen na het element afterHTML(html, options); streamAfterHTML(options);
De nieuwe invoeg- en streamingmethoden

Er zijn ook Unsafe-versies die we binnenkort behandelen. Hoewel er veel lijken te zijn (vooral als je de Unsafe-equivalenten toevoegt), maakt de consistente naamgevingsconventie duidelijker wat elke methode doet in vergelijking met de niet-gerelateerde methoden die eerder zijn genoemd.

De statische versies nemen nieuwe HTML als een DOM-tekenreeksargument, samen met optionele opties:

const newHTML = "<p>This is a new paragraph</p>";
const contentElement = document.querySelector('#content-to-update');

contentElement.setHTML(newHTML);

De streamingversies werken met de Streams API, zoals met een getWriter():

const contentElement = document.querySelector('#content-to-update');
const writer = contentElement.streamHTMLUnsafe().getWriter();

// Example stream of updating content
while (true) {
  await writer.write(`<p>${++i}</p>`);
  await new Promise((resolve) => setTimeout(resolve, 1000));
}

writer.close();

Of, als alternatief, vanuit een ophaalreactie met pipe-ketens:

const contentElement = document.querySelector('#content-to-update');
const response = await fetch('/api/content.html');

response.body
  .pipeThrough(new TextDecoderStream())
  .pipeTo(contentElement.streamHTMLUnsafe());

textStream()-gemaksmethode

Browser Support

  • Chrome: 151.
  • Edge: 151.
  • Firefox: not supported.
  • Safari: not supported.

Source

Er is ook een textStream-gemaksmethode toegevoegd, waarmee je rechtstreeks kunt streamen zonder de tussenstap TextDecoderStream():

const contentElement = document.querySelector('#content-to-update');
const response = await fetch('/api/content.html');

response.textStream().pipeTo(contentElement.streamHTMLUnsafe());

options

Met het argument options kun je een aangepaste sanitizer invoeren. De standaardwaarde is default, wat de standaardconfiguratie van de sanitizer betekent. Het wordt zo gebruikt:

const newHTML = '<p>This is a new paragraph</p>';
const contentElement = document.querySelector('#content-to-update');

// Only allows basic formatting
const basicFormattingSanitzer = new Sanitizer({ elements: ['em', 'i', 'b', 'strong'] });

contentElement.setHTML(newHTML, {sanitizer: basicFormattingSanitzer});

'Onveilige' methoden

Er zijn ook 'onveilige' versies van elk van de API's:

Actie Statisch Streaming
De HTML-content van het element instellen setHTMLUnsafe(html,options); streamHTMLUnsafe(options);
Het hele element vervangen door deze HTML replaceWithHTMLUnsafe(html, options); streamReplaceWithHTMLUnsafe(options);
De HTML toevoegen vóór het element beforeHTMLUnsafe(html, options); streamBeforeHTMLUnsafe(options);
De HTML toevoegen als het eerste onderliggende element van het element prependHTMLUnsafe(html, options); streamPrependHTMLUnsafe(options);
De HTML toevoegen als het laatste onderliggende element van het element appendHTMLUnsafe(html, options); streamAppendHTMLUnsafe(options);
De HTML toevoegen na het element afterHTMLUnsafe(html, options); streamAfterHTMLUnsafe(options);
De 'onveilige' invoeg- en streamingmethoden

Deze 'onveilige' methoden zetten de sanitizer standaard uit. Je kunt een aangepaste sanitizer opgeven als je wilt. Met deze methoden kunnen scripts ook worden uitgevoerd met een optionele runScripts-optie, die standaard is ingesteld op false.

Net als setHTML is setHTMLUnsafe een bestaande methode, maar de parameter runScripts is eraan toegevoegd zodat deze kan worden gebruikt met scriptuitvoering:

const newHTML = `<p>This is a new paragraph</p>
                 <script src=script.js></script>`;
const contentElement = document.querySelector('#content-to-update');

contentElement.setHTMLUnsafe(newHTML, {runScripts: true});

De bewoording 'unsafe' in de methode is bedoeld om ontwikkelaars te herinneren aan het potentiële risico en hoe ze scripts kunnen opschonen of beperken, niet om te zeggen dat deze methoden niet mogen worden gebruikt.

Hoe onveilig dit is, hangt af van hoe betrouwbaar de invoer is. De statische methoden van Unsafe werken allemaal met zowel DOM-tekenreeks als TrustedHTML als de html-argumenten en staan ook toe dat opschoningsprogramma's worden gebruikt. Met runScript is het de bedoeling om scripts toe te staan. Daarom wordt er standaard geen sanitizer gebruikt.

Toepassingen

Met deze nieuwe API's kunnen ontwikkelaars makkelijker HTML toevoegen aan bestaande pagina's. Er worden nieuwe API's toegevoegd met consistente namen en opties. De streaming-API's bieden de prestatievoordelen dat je niet hoeft te wachten tot alle nieuwe content beschikbaar is op het platform.

Use cases hiervan zijn onder andere:

  • Dynamische streaming van grote contentupdates in apps van één pagina. Zoals eerder vermeld, is een groot nadeel van de huidige SPA-architectuur dat deze niet profiteert van de streaming-aard van de eerste HTML-loads, tot nu toe.
  • Veelgebruikte content invoegen, zoals HTML-voetteksten. Met de JavaScript-API's kunt u gedeeltelijke pagina's ophalen en deze op de pagina invoegen. Zo profiteert u van caching in plaats van dat u ze herhaalt op elke pagina die u stuurt. Omdat deze methode afhankelijk is van JavaScript, mag deze alleen worden gebruikt voor content die niet zichtbaar is bij het eerste laden.

Dit zijn maar een paar voorbeelden en we zijn benieuwd naar jullie ideeën.

Beperkingen en subtiliteiten

Deze nieuwe API's bevatten ook een paar beperkingen en subtiliteiten waar je rekening mee moet houden:

  • Voor de integratie van streaming met de Trusted Types API is een nieuwe createParserOptions-methode vereist waarmee een sanitizer kan worden geïnjecteerd in een HTML-instelbewerking. Ga naar de uitleg voor meer informatie over de integratie van vertrouwde typen.
  • Net als bij <template for> kan het verplaatsen van elementen waarnaar wordt gestreamd onverwachte gevolgen of streamfouten veroorzaken.
  • streamHTMLUnsafe werkt in veel opzichten meer als de hoofdparser, waaronder de verwerking van <template for>-instructies wanneer ze aan het hoofddocument worden toegevoegd en het uitstellen van defer-scripts tot het einde van de stream.

Standardization status

De nieuwere invoeg- en streamingmethoden worden op dit moment toegevoegd aan de HTML-standaard, maar worden nog niet in alle browsers ondersteund.

Polyfill

Het Chrome-team heeft een html-setters-polyfill uitgebracht die beschikbaar is op npm, zodat sites deze nieuwe functionaliteit meteen kunnen gebruiken, zelfs voordat deze in andere browsers beschikbaar is.

Deze polyfill streamt niet, maar buffert en past toe wanneer de stream is voltooid. Het is meer een polyfill voor de API-vorm dan voor de functionaliteit.

Daarnaast is de instelling van veilige content afhankelijk van setHTML en de Sanitizer API, die niet wordt ondersteund in Safari.

Gebruik deze samen

Hoewel dit 2 afzonderlijke API's zijn, is de combinatie ervan pas echt krachtig. Door nieuwe <template for>-elementen naar de HTML te streamen, kun je verschillende delen van de content dynamisch updaten zonder dat je elk deel rechtstreeks hoeft te targeten met afzonderlijke JavaScript-verwijzingen naar het DOM.

Een basispagina in SPA-stijl kan worden geïmplementeerd door een overzichtspagina met verwerkingsinstructies te laden en daarna de templates van elke nieuwe pagina naar de onderkant van de HTML te streamen om in die verwerkingsinstructies te passen.

Er zijn ongetwijfeld meer mogelijkheden en use cases voor beide API's, dus laat je niet tegenhouden door onze (beperkte!) verbeelding. Door gedeeltelijke updates makkelijker te beheren, kun je een deel van de boilerplate-code verminderen, updates makkelijker maken en nieuwe mogelijkheden voor het web ontsluiten.

Chrome werkt aan nog een paar API's in het kader van het project Declarative Partial Updates, maar we zijn blij dat we deze eerste 2 al kunnen aanbieden. We houden je op de hoogte en laten het je weten als er meer beschikbaar is in deze ruimte.