> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.
# HTMLRewriter
> Parse and transform HTML with streaming HTMLRewriter API
Bun implements the HTMLRewriter API for parsing and transforming HTML documents using CSS selectors. It's based on Cloudflare Workers' HTMLRewriter and uses the lol-html parser.
## Basic Usage
```ts theme={null}
const rewriter = new HTMLRewriter();
rewriter.on("p", {
element(element) {
element.setInnerContent("Hello World!");
},
});
const input = "Original
";
const output = rewriter.transform(new Response(input));
console.log(await output.text());
// Hello World!
```
## Selecting Elements
### CSS Selectors
Use any valid CSS selector:
```ts theme={null}
const rewriter = new HTMLRewriter();
// Tag selectors
rewriter.on("p", handlers);
rewriter.on("div", handlers);
// Class selectors
rewriter.on(".my-class", handlers);
// ID selectors
rewriter.on("#header", handlers);
// Attribute selectors
rewriter.on('[data-user-id="123"]', handlers);
rewriter.on('a[href^="https://"]', handlers);
// Combinators
rewriter.on("div > p", handlers); // Direct child
rewriter.on("div p", handlers); // Descendant
rewriter.on("h1 + p", handlers); // Adjacent sibling
// Pseudo-classes
rewriter.on("li:first-child", handlers);
rewriter.on("p:not(.ignore)", handlers);
```
### Multiple Selectors
```ts theme={null}
const rewriter = new HTMLRewriter();
// Different handlers for different selectors
rewriter.on("h1", {
element(el) {
el.setAttribute("class", "title");
},
});
rewriter.on("p", {
element(el) {
el.setAttribute("class", "paragraph");
},
});
```
## Element Handlers
### Element Handler
Called when an element is encountered:
```ts theme={null}
rewriter.on("div", {
element(element) {
console.log("Found div:", element.tagName);
},
});
```
### Text Handler
Called for text nodes:
```ts theme={null}
rewriter.on("p", {
text(text) {
if (text.text.includes("TODO")) {
text.replace("[PENDING]");
}
},
});
```
### Comment Handler
Called for HTML comments:
```ts theme={null}
rewriter.on("div", {
comments(comment) {
if (comment.text.includes("debug")) {
comment.remove();
}
},
});
```
## Modifying Elements
### Attributes
```ts theme={null}
rewriter.on("img", {
element(element) {
// Get attribute
const src = element.getAttribute("src");
// Set attribute
element.setAttribute("loading", "lazy");
// Remove attribute
element.removeAttribute("width");
// Check if attribute exists
if (element.hasAttribute("alt")) {
console.log("Has alt text");
}
},
});
```
### Content
```ts theme={null}
rewriter.on("div", {
element(element) {
// Replace all content
element.setInnerContent("New content");
// Replace with HTML
element.setInnerContent("Paragraph
", { html: true });
// Prepend content
element.prepend("Start: ");
element.prepend("Bold ", { html: true });
// Append content
element.append(" :End");
element.append("Italic ", { html: true });
},
});
```
### Insertion
```ts theme={null}
rewriter.on("h1", {
element(element) {
// Insert before element
element.before("Navigation ", { html: true });
// Insert after element
element.after("Hello
-> Hola
```
## Performance
### Streaming Benefits
HTMLRewriter processes HTML as it streams:
```ts theme={null}
const rewriter = new HTMLRewriter();
rewriter.on("img", {
element(element) {
element.setAttribute("loading", "lazy");
},
});
// Starts transforming before entire HTML is downloaded
const response = await fetch("https://example.com/large.html");
const transformed = rewriter.transform(response);
// Can start reading output immediately
const reader = transformed.body.getReader();
const { value } = await reader.read();
console.log("First chunk:", value);
```
### Memory Efficiency
```ts theme={null}
// Bad - loads entire HTML into memory
const html = await response.text();
const modified = html.replace(/