` and `` are left alone. This behavior can be [disabled](/api/create#collapse) if needed. ```ts run html` <ul> <li>a</li> <li>b</li> </ul>`; ``` <!-- /security/limits --> # What it does not do The guarantee is narrow and worth stating exactly: **values interpolated into a template are escaped for the context they land in, and URLs are scheme-checked.** Everything below is outside that line. ## It escapes values, it does not clean markup This is not a sanitizer. Given a string of HTML from a user, it has nothing to offer: escaping it shows the tags as text, and `raw()` publishes whatever it contained. There is no third option here. To accept markup from people — comment bodies, a rich-text field, anything pasted — run it through a sanitizer first and `raw()` the result. ```ts import DOMPurify from 'dompurify'; html`<div class="comment">${raw(DOMPurify.sanitize(userMarkup))}</div>`; ``` Rendering user text, rather than user markup, needs none of this. `${userText}` is already safe. ## A tag name in `raw()` `<${raw(name)}>` is taken on trust, like any `raw()`: the scanner cannot see which element it opens, so it reads what follows as ordinary markup. If the name is `script` or `style`, a value after it is escaped as text, and escaped text in a script still runs. Pick dynamic tag names from a fixed list, as in ``raw(`h${level}`)`` with a checked `level`, never from input. ## `trusted` writes values as they are {#trusted} [`trusted`](/api/html#trusted) gives up escaping for speed. In production, anything a value holds reaches the page as it is, and its output nests into `html` without being escaped again. The development build throws [code 20](/reference/errors#e20) for any value that needs escaping, but it only sees the data that runs through it in development. A field that later starts taking user input is not caught. To keep it out of a codebase, ban the import. ESLint's `no-restricted-imports` does it, and so does oxlint's: ```json { "no-restricted-imports": [ "error", { "paths": [{ "name": "@itsy/html", "importNames": ["trusted"], "message": "Use html." }] } ] } ``` ## Data in a script block `JSON.stringify` does not escape `<`, and a `</script>` inside the data ends the block early however the JSON is quoted. This is the one escape the library cannot do, because the contents of a script are `raw()` by definition. ```ts const data = raw(JSON.stringify(state).replace(/</g, '\\u003c')); html`<script type="application/json" id="data">${data}</script>`; ``` Or use a serializer that already handles it, such as devalue or serialize-javascript. ## Content Security Policy The library writes no inline event handlers — `on*` is refused outright — so a policy without `unsafe-inline` for scripts is compatible as written. For the inline scripts and styles a page does add, `frame({ nonce })` puts the nonce on every script and style entry that does not have one. Generate it per request. ```ts const nonce = crypto.randomUUID(); frame({ lang: 'en', title, scripts, nonce }); ``` Ready-made `Html` passed into `head` or `scripts` is left alone, nonce included. An element built by hand needs its nonce added by hand. ## It is not an HTML validator The [markup check](/guide/checks) catches what a browser would silently repair — unclosed tags, stray end tags, nesting the parser rewrites — and the [accessibility rules](/api/check#accessibility) in `check()` report common failures such as an `<img>` with no `alt` or a field with no label. Neither knows the content model, so a `<div>` inside a `<span>` passes, and neither follows the heading outline, so levels that skip a rank pass too. Use html-validate for the content model, and a full accessibility audit such as axe-core for what the rules leave out. ## No async A `Promise` in a template throws [code 7](/reference/errors#e7). Await data before building the markup. The renderer being synchronous end to end is what lets the same function run in a browser with no build step. <!-- /security/url-guard --> # The URL guard Escaping cannot make `javascript:alert(1)` safe, because there is nothing in it to escape. So URL attributes get a second check: the scheme has to be one of a short list, or the value is replaced. ```ts run html` <a href="${'/docs'}">relative: always passes</a> <a href="${'https://x.y'}">an allowed scheme: passes</a> <a href="${'javascript:alert(1)'}">anything else: replaced</a>`; ``` The attributes checked are `href`, `src`, `action`, `formaction`, `data` and `xlink:href`. `srcset` is escaped but not checked: an image URL cannot run script. The allowed schemes are `http`, `https`, `mailto`, `tel`, `data` and `blob`. A URL with no scheme — any relative URL — always passes. Anything else renders as `about:blank#blocked`. ## It never throws A blocked URL is bad data, not a mistake in the markup, and data must not be able to crash a page render. So the guard substitutes rather than throwing. To find out whether it fired, run [`check()`](/guide/checks#check) over the rendered page: every blocked URL is reported as [code 19](/reference/errors#e19). ## It reads a URL the way a browser does Browsers ignore whitespace and control characters while reading a scheme, so a check on the raw string is not enough. The guard strips those and lowercases before looking for a scheme. An `Html` from `raw()` is checked the same way. ```ts run html` <a href="${' JaVa\tScRiPt:alert(1)'}">…</a> <a href="${'javascript:alert(1)'}">…</a> <a href="${raw('javascript:x')}">…</a>`; ``` The entity case is worth following. `javascript:` does not start with a letter, so it has no scheme as far as the guard is concerned and passes through — as `javascript:`. The browser then reads that as the literal characters `javascript:`, which is not a scheme it knows. It is inert either way. ## Adding a scheme `createHtml` returns an `html` and `attrs` with their own scheme list. Call it once, at module scope. ```ts import { createHtml, SCHEMES } from '@itsy/html/create'; export const { html, attrs } = createHtml({ schemes: [...SCHEMES, 'sms'] }); ``` `schemes` replaces the set rather than extending it, so spread `SCHEMES` to keep the defaults — `createHtml({ schemes: ['https'] })` allows https and nothing else, which is sometimes exactly what is needed. For one link, widening the guard for a whole page is the wrong size of tool. Write the tag: ```ts html`<p>${raw('<a href="sms:+4712345678">Text us</a>')}</p>`; ``` ::: warning `frame` and `wrap()` always use the default set. A scheme allowed through `createHtml` is still blocked in a frame head entry or a `wrap()` attribute. ::: ## Two things it does not cover ::: details `data:` is allowed, and `data:text/html` is a real document `data:` is on the list so inline images work. But a `data:text/html` URL in an `<iframe>`, `<object>` or `<embed>` renders whatever it carries, in its own origin. If such a URL can come from a user, check its MIME type first, or use `createHtml({ schemes: [...] })` with `data` left out. ::: ::: details `srcset` is escaped but not checked Its URLs are not scheme-checked. An image URL cannot run script, and parsing the comma-and- descriptor format correctly is not worth what it would cost every user of the library. ::: <!-- /recipes/client --> # In a browser ```ts import { Results } from './results.ts'; document.querySelector('#results').innerHTML = Results(items).markup; ``` ## Behaviour goes on with a listener Event handler attributes are refused, so behaviour is attached rather than written into the markup. One delegated listener on a container handles a list of any size, and keeps working after the list is re-rendered. ```ts const list = document.querySelector('#results'); list.addEventListener('click', (e) => { const button = e.target.closest('button[data-url]'); if (!button) return; toggleSaved(button.dataset.url); }); ``` This is why [the example in Getting started](/guide/getting-started#a-component) puts `data-url` on the button. The markup carries the data; the listener carries the behaviour. ## Custom elements for anything stateful For a component that owns state over time, render the markup with a template and upgrade it with a custom element. ```ts class SaveButton extends HTMLElement { connectedCallback() { this.addEventListener('click', () => this.toggle()); } toggle() { const pressed = this.getAttribute('aria-pressed') === 'true'; this.setAttribute('aria-pressed', String(!pressed)); } } customElements.define('save-button', SaveButton); ``` ```ts html`<save-button ${attrs({ 'aria-pressed': saved, 'data-url': url })}>Save</save-button>`; ``` ::: tip Re-render the piece, not the page Assigning to `innerHTML` throws away the nodes inside and their state — focus, scroll position, an open `<details>`. Ideally, render the smallest region that changed, or use a custom element that updates itself in place. ::: ## Importing less If the browser only needs `cx()` and `attrs()` for class and style lists, `@itsy/html/attrs` provides them without the template scanner. See [the import map](/reference/imports). <!-- /recipes/server --> # On a server The renderer returns one string, synchronously. There is nothing to await and no framework integration to install — set the content type and send it. ::: code-group ```ts [Hono] import { Hono } from 'hono'; import { frame } from '@itsy/html/frame'; const app = new Hono(); app.get('/orders', (c) => { const view = frame({ lang: 'en', title: 'Orders', content: Orders(data) }); return c.html(view.markup); }); ``` ```ts [Fastify] import Fastify from 'fastify'; import { frame } from '@itsy/html/frame'; const app = Fastify(); app.get('/orders', (_req, reply) => { const view = frame({ lang: 'en', title: 'Orders', content: Orders(data) }); reply.type('text/html; charset=utf-8').send(view.markup); }); ``` ```ts [node:http] import { createServer } from 'node:http'; import { frame } from '@itsy/html/frame'; createServer((_req, res) => { const view = frame({ lang: 'en', title: 'Orders', content: Orders(data) }); res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); res.end(view.markup); }).listen(3000); ``` ::: ::: warning Send `view.markup` `Html` is an object. Express, Fastify and Koa send an object as JSON, and their types accept it, so nothing flags it before a request does. [What each one does](/api/html#handing-it-over). ::: ## The page is one string There is no streaming and no partial flush. `frame()` builds the whole document and hands it over. For most pages that is the simpler trade: no suspense boundaries, no out-of-order chunks, and the `Content-Length` is known. To send a shell before the data is ready, send two responses — a fast page and a fetch — rather than trying to split a template. ## A nonce per request `frame({ nonce })` adds the nonce to every script and style entry that has none of its own. ```ts app.get('/orders', (c) => { const nonce = crypto.randomUUID(); c.header('content-security-policy', `script-src 'nonce-${nonce}'; object-src 'none'`); return c.html(frame({ lang: 'en', title: 'Orders', content, scripts, nonce }).markup); }); ``` The library never writes an inline event handler, so a policy with no `unsafe-inline` for scripts works as-is. See [what it does not do](/security/limits#content-security-policy). ## Check the output in development ```ts import { check } from '@itsy/html/check'; if (process.env.NODE_ENV !== 'production') { for (const p of check(view)) console.warn(`[${'rule' in p ? p.rule : `html ${p.code}`}] ${p.message}`, p.near); } ``` In the production build `check()` returns `[]`, so the guard above is about skipping the loop, not about safety. Leaving the call in unguarded is fine. <!-- /recipes/testing --> # Testing Components are functions returning strings, so they need no renderer, no DOM and no test harness beyond whatever the project already runs. ```ts import { test } from 'node:test'; import assert from 'node:assert/strict'; const Item = (label: string) => html`<li>${label}</li>`; test('escapes the label', () => { assert.equal(Item('a < b').markup, '<li>a < b</li>'); }); ``` ## Assert the markup is clean `check()` returns the problems in a rendered page, so the general-purpose assertion is that there are none. ```ts import { check } from '@itsy/html/check'; test('the page is well formed', () => { assert.deepEqual(check(Page(data)), []); }); ``` That one line covers unclosed tags, mismatched end tags, nesting a browser would rewrite, duplicate attributes, duplicate ids, id references pointing nowhere, any URL the guard blocked, and the [accessibility rules](/api/check#accessibility). Run it over the page rather than a fragment — the ids and the references are only visible at page level, and so are the `<html>`, the `<title>` and the `for` targets that three of the accessibility rules read. Pass `{ a11y: false }` for the markup check on its own. When it fails, the array says where: ```ts for (const p of check(Page(data))) console.log('rule' in p ? p.rule : p.code, p.message, p.near); ``` ## Confirm the dev build In the production build `check()` always returns `[]`. A suite that resolves the production build will pass every markup assertion, whatever the markup is. Run tests with the condition set: ```sh node --conditions=development --test test/*.test.ts ``` And to be certain the suite cannot pass vacuously, assert that the checks are on. `check.enabled` is `false` on the production build: ```ts test('the checks are active', () => assert(check.enabled)); ``` ::: tip Vitest resolves through Vite, which applies the `development` condition in dev. When it is unclear which build a runner resolved, the assertion above answers it in one run. ::: ## Storybook A decorator runs the check on every story, so a broken component fails right in the story being viewed. ```ts // .storybook/preview.ts export const decorators = [ (story) => { const markup = story().markup; for (const p of check(markup)) console.warn(`[${'rule' in p ? p.rule : `html ${p.code}`}] ${p.message}`, p.near); return markup; }, ]; ``` ## Snapshots Snapshot `view.markup`, never the `Html` itself — a serializer will otherwise record an object. ```ts expect(Page(data).markup).toMatchSnapshot(); // or the runner's equivalent ``` Whitespace in the output is stable: [static markup collapses to single spaces](/guide/writing-html#whitespace), so reindenting a template does not churn the snapshot. Reflowing a line does, since a newline becomes a space. <!-- /recipes/tooling --> # Bundlers and editors ## Choosing the development build The dev build spells out error messages and runs [the markup check](/guide/checks). The production build throws the same `HtmlError.code` with the message `E6` and skips the check. Bundlers pick between them with the `development` export condition. ::: code-group ```txt [Vite] Nothing to do. Vite sets the development condition during dev and drops it for a production build, so the right one is used either way. ``` ```js [esbuild] // esbuild.config.js await esbuild.build({ entryPoints: ['src/app.ts'], bundle: true, conditions: dev ? ['development'] : [], }); ``` ```sh [Node] node --conditions=development server.js ``` ```sh [node --test] node --conditions=development --test test/*.test.ts ``` ::: ::: warning Without the condition, resolution falls back to the production build, where `check()` returns `[]` and every markup mistake goes unreported. A test suite on the production build passes whatever is written. See [testing](/recipes/testing#confirm-the-dev-build). ::: ## Formatters rewrite embedded markup Prettier and oxfmt both format embedded languages by default. Inside an `html` template that means `<br>` becomes `<br />`, which the markup check then reports as [code 11](/reference/errors#e11), and a `${}` inside `<script>` can pick up a stray `;`. ::: code-group ```json [.prettierrc] { "embeddedLanguageFormatting": "off" } ``` ```ts [oxfmt.config.ts] import { defineConfig } from 'oxfmt'; export default defineConfig({ embeddedLanguageFormatting: 'off', }); ``` ::: ## Syntax highlighting Most editors highlight a tagged template by the name of its tag, and `html` is the name every lit-html-aware tool already looks for — so highlighting usually works with no configuration. Where it does not, a comment before the backtick is understood by most tooling and costs nothing at runtime: ```ts const view = /* html */ `<p>…</p>`; ``` For VS Code, the lit-html extension adds highlighting, bracket matching and folding inside `html` templates. It does not need lit to be installed. ## TypeScript Nothing to configure. `html` is typed as a tag over `Renderable`, so an object or a `Promise` in a template is a type error before it is a runtime one, and `Html` has a private field that keeps a plain string from passing as one. The package is ESM only. `"module": "ESNext"` with `"moduleResolution": "bundler"` — or `"node16"` and up — resolves the six entry points; anything older will not see them. <!-- /api/attrs --> # @itsy/html/attrs ```ts import { attrs, cx, esc } from '@itsy/html/attrs'; ``` Independent of the template scanner. `attrs` and `cx` are also exported from the root, so importing from here is only worth it when nothing else from the library is needed. ## attrs ```ts attrs(values: Record<string, AttrValue>): Html ``` Renders attributes for use inside a tag. ```ts html`<input ${attrs({ type: 'search', disabled: busy, class: ['field', error && 'is-invalid'] })}>`; ``` | key | behaviour | | --------------- | ---------------------------------------------------------------- | | `class` | anything [`cx()`](#cx) accepts | | `style` | an object; keys written as given, `null` and `undefined` dropped | | `aria` | an object, spread to `aria-*` | | `data` | an object, spread to `data-*` | | a URL attribute | escaped and [scheme-checked](/security/url-guard) | | anything else | escaped | Booleans follow [two rules](/guide/writing-html#attributes): `aria-*`, `draggable`, `spellcheck` and `contenteditable` render `"true"` and `"false"`; every other attribute renders the bare name for `true` and is left out for `false`. Attribute names are written out exactly as given — no camelCase conversion, no list of known attributes. Throws [code 2](/reference/errors#e2) for an object or array on a key other than the four above, and [code 3](/reference/errors#e3) for any `on*` key. ## cx ```ts cx(...values: ClassValue[]): string ``` Joins class names. Falsy values and `true` contribute nothing. ```ts cx('btn', active && 'btn-active'); // 'btn btn-active' cx({ open, disabled: !ready }); // keys whose value is truthy cx(['a', ['b', null]], 0, '', undefined); // 'a b' ``` Returns a plain string, so it is escaped like any other value when it lands in a template. ## esc ```ts esc(text: string): string ``` Escapes `&`, `<`, `>`, `"` and `'`. It is what the renderer uses for text and attribute values. It is needed only when assembling markup by hand to pass to `raw()`. Prefer putting the value in a template, where the context chooses the escaping. <!-- /api/check --> # @itsy/html/check ```ts import { check } from '@itsy/html/check'; import type { Problem, Finding, RuleSet, Visitor, Report, A11yRule, A11yOptions, CheckOptions } from '@itsy/html/check'; ``` Everything the library checks, including: the [markup check](/guide/checks) over a rendered page, [twenty-five accessibility rules](#accessibility) that run by default, and a [hook for adding additional rules](#custom-rules). All of it is development-only — the production build compiles `check` down to a function that immediately returns an empty array, 28 bytes. ## check ```ts check(markup: string | Html, options?: CheckOptions): (Problem | Finding)[] ``` Runs the checks over a rendered string rather than a single template, and returns what it found in page order. Empty means clean. ```ts assert.deepEqual(check(Page(data)), []); ``` Because it sees the finished page, it catches what one `html` call cannot: - problems that span two templates, or hide inside `attrs()` output - [code 15](/reference/errors#e15), an id reference with no matching id - [code 16](/reference/errors#e16), an id used twice - [code 19](/reference/errors#e19), a URL the guard replaced with `about:blank#blocked` - the [accessibility rules](#accessibility), which need the finished markup for the same reason ::: danger Always `[]` in the production build There is no check in the production build, so `check()` there returns an empty array whatever it is passed. A test suite that resolves the production build will pass every assertion based on it. Assert [`check.enabled`](#check-enabled) once and it cannot. See [confirming the dev build](/recipes/testing#confirm-the-dev-build). ::: ## CheckOptions ```ts interface CheckOptions { ids?: boolean; // default true a11y?: boolean | A11yOptions; // default true rules?: RuleSet | readonly RuleSet[]; } interface A11yOptions { without?: readonly A11yRule[]; // rules to silence, by name } ``` `ids: false` turns off codes 15 and 16. Use it when checking a fragment rather than a page, where an id reference pointing outside the fragment is expected. `a11y: false` leaves only the markup check, and narrows the return type back to `Problem[]`. `rules` runs [custom rules](#custom-rules) in the same pass. The ids checked are `for`, `form`, `list`, `headers`, `popovertarget`, `commandfor`, `itemref` and the `aria-*` relations. ## Problem ```ts interface Problem { code: number; // the same numbers as HtmlError.code message: string; // what is wrong, and what the browser does instead at: number; // character offset into the markup near: string; // the markup around `at`, whitespace squeezed } ``` In a template, a `${…}` counts as those four characters when `at` is computed. ## Finding What a rule reports. The list holds both shapes, and the two are told apart by their first field: ```ts interface Finding { rule: string; // which rule found it, e.g. img-alt message: string; // what is wrong, and what it means for a person using the page at: number; near: string; } for (const p of check(view)) { if ('rule' in p) console.warn(`[${p.rule}] ${p.message}`, p.near); else console.warn(`[html ${p.code}] ${p.message}`, p.near); } ``` Names, not numbers, and deliberately: these are not [`HtmlError` codes](/reference/errors). Nothing here ever throws, and a name says what it found without a lookup. ## Accessibility Advice rather than correctness, but in the same pass and the same list, because a finding that has to be asked for is a finding nobody sees. They cost nothing to leave on: they compile away with the rest of `check()`. An empty list means these rules found nothing, not that the page is accessible. | rule | fires on | | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | `img-alt` | an image the browser exposes with no name: `<img>` with no `alt`, `<input type="image">`, `role="img"` | | `img-alt-filename` | `alt` that is only a file name, like `photo-3.png` | | `a-href` | `<a>` with no `href`, `id`, `name`, `tabindex`, `role` or `aria-disabled` | | `html-lang` | `<html>` with no `lang`, or only whitespace in it | | `iframe-title` | an `<iframe>` in the tab order with no `title` | | `empty-heading` | a heading — `<h1>`…`<h6>` or `role="heading"` — with no text and nothing naming it | | `empty-link` | a link — `<a href>` or `role="link"` — with no text and nothing naming it; `<area href>` with no `alt` | | `empty-button` | a button — `<button>`, `role="button"`, `<input type="button">` — with no text and nothing naming it | | `empty-title` | the page's `<title>` with no text, or a whole page with no `<title>` at all | | `field-label` | a form field with no `<label>`, `aria-label`, `aria-labelledby` or `title` | | `label-control` | `<label>` with no `for` and no control inside it | | `label-for` | `for=` pointing at something that is not a form control | | `aria-unknown` | an `aria-*` name that does not exist | | `aria-empty` | an `aria-*` attribute or `role` with an empty value | | `aria-boolean` | a true/false ARIA attribute given something else | | `aria-value` | an ARIA number, whole number or token given a value it does not take | | `aria-live` | `aria-live` outside `polite`, `assertive` and `off` | | `aria-hidden-focus` | something the keyboard can tab to, on or inside `aria-hidden="true"` | | `positive-tabindex` | `tabindex` above zero | | `figcaption-parent` | `<figcaption>` that is not a direct child of `<figure>` | | `misplaced-scope` | `scope` on anything but `<th>` | | `role-unknown` | a `role` that is not an ARIA, DPUB-ARIA or Graphics ARIA role | | `role-redundant` | a `role` the element already had | | `role-required-props` | a role with no state to read, like `checkbox` with no `aria-checked` | | `role-presentation-conflict` | `role="none"` or `alt=""` the browser must ignore: on something focusable, or with a global `aria-*` | ```ts run check('<img src="cat.jpg"><button><svg></svg></button><nav role="navigation">x</nav>'); ``` ### Turning rules off ```ts check(view, { a11y: { without: ['img-alt-filename', 'positive-tabindex'] } }); ``` The names are checked against `A11yRule`, the union of the twenty-five above, so a typo is a type error rather than a rule that quietly stays on: ```ts check(view).some((p) => 'rule' in p && p.rule === 'img-altt'); // ✗ type error ``` Reach for it when a rule is wrong for a whole codebase. `a11y: false` turns the lot off. ### Turning one element off Prefer markup that says why. The rules already respect the attributes that mean "no name needed", and unlike a suppression comment those tell a screen reader the same thing: ```ts run [ check('<img src="hero.jpg" alt="">'), // decoration, said properly check('<img src="hero.jpg" role="presentation">'), check('<img src="hero.jpg" aria-hidden="true">'), check('<div hidden><img src="hero.jpg"></div>'), ]; ``` There is no `data-a11y-ignore` attribute and there will not be one. This library renders exactly what is written, so a suppression marker would ship to every visitor — an ESLint comment is stripped at build, an attribute is not. ### Quiet by design A rule that fires on correct markup is worse than one that misses a bug, because one wrong finding is all it takes for someone to switch the whole thing off. So the rules stay quiet whenever they cannot be sure: - Nothing inside `hidden`, `inert`, `display: none`, `visibility: hidden`, `aria-hidden="true"` or `<template>` is reported. None of it reaches the person the rules are about — except that the keyboard still reaches what `aria-hidden` hides, which is what `aria-hidden-focus` is for. - Each rule goes by the role the browser gives the element, not by its tag. `<span role="button">` is a button, `<a href role="doc-biblioref">` is a link, and `<h2 role="none">` is no heading. - `alt=""`, `role="presentation"` and `role="none"` mark an image as decoration, and all three are respected — until the browser has to ignore them, on anything focusable or anything with a global ARIA attribute such as `aria-label`. Then the element keeps its role, and the rules read it as what it is. - A custom element can hold anything, so it silences the rule around it — a `<my-input>` inside a `<label>` counts as the control, a `<my-icon>` inside a `<button>` counts as a name, and a custom element with `role="switch"` may carry its `aria-checked` through `ElementInternals`. - A name from `aria-label`, `aria-labelledby` or `title`, on the element or on anything inside it, counts as text. `<button><img src="i.svg" alt="Delete"></button>` is silent. A name from `aria-labelledby` is taken on trust: the rules check that it says something, not what the element it points at holds, and a reference to an id that is not on the page is [code 15](/reference/errors#e15). - Text counts only where someone reads it: not inside `aria-hidden`, and not in a `<script>` or a `<style>`. - The role tables hold only the mappings the markup settles on its own. `<header role="banner">`, `<aside role="complementary">`, `<li role="listitem">` and `<option role="option">` depend on an ancestor, so none of them is reported as redundant. - Nor is `<ul role="list">`, or `role="table"`, `role="caption"`, `role="rowgroup"` and `role="row"` on the table elements that already have them. Safari drops the list role from a list styled `list-style: none`, browsers have dropped the table roles from a table given another `display`, and restating the role puts it back. - An `<input>` keeps its own state whatever role it is given. `<input type="checkbox" role="switch">` is the native switch, and needs no `aria-checked` — ARIA in HTML forbids one. A text input with a `list` is a combobox already, and needs no `aria-expanded`. - `role` takes a fallback list, and the browser uses the first entry it knows. WebKit's `role="text"` is known to WebKit alone, so an element that carries it has no role the rules can be sure of, and they leave it be. - The rules that need the full role-to-properties graph — which `aria-*` each role allows — are left out. That table is the largest and the easiest one to be wrong with. ### Held to outside sources The rules are not checked against their own idea of what is right. The test suite holds them to: - **The W3C ACT Rules.** Every example the ACT Rules Community Group publishes for a rule here runs through `check()`: a `failed` example must be reported, a `passed` or `inapplicable` one must not be. - **ARIA and HTML-AAM**, through aria-query, which is generated from them. The role, attribute and value tables are compared entry by entry. Where the rules part ways with either on purpose — ARIA 1.3 has moved on from what the source encodes, or the markup alone cannot settle the answer — the difference is listed in the suite with its reason, and one that stops being a difference fails it. The markup check is held the same way: over the html5lib parser suite, whenever it reports nothing, or only what it repairs as the browser does, the tree it read is the one a spec-conformant parser builds; and over every three-deep nesting of the elements the parser treats specially, it reports a problem exactly when that parser changes what is written. ## Custom rules `rules` runs a project's own rules in the same walk, reporting into the same list: house style, design-system constraints, anything that reads as markup. ```ts run const noInlineStyle = (report) => ({ open(tag, attrs, at) { if (attrs.has('style')) report('no-inline-style', `\`<${tag} style>\`: use a utility class`, at); }, }); check('<p style="color:red">x</p>', { a11y: false, rules: noInlineStyle }); ``` ```ts type RuleSet = (report: Report) => Visitor; type Report = (rule: string, message: string, at: number) => void; interface Visitor { open?: (tag: string, attrs: ReadonlyMap<string, string>, at: number, ancestors: readonly string[]) => void; text?: (content: string, at: number, ancestors: readonly string[]) => void; close?: (tag: string, at: number, hadText: boolean) => void; end?: (ids: ReadonlyMap<string, number>) => void; } ``` A rule set is called once per `check()` and returns a visitor, so per-run state goes in the closure. Every hook is optional, and `near` is filled in automatically — a rule never looks at the markup itself. - **`open`** — a start tag. `attrs` has lowercased names and verbatim values; a bare attribute is present with an empty value. `ancestors` is outermost first, and holds what is _really_ open: anything the browser would have closed already is closed. A rule may keep both. A void element opens and never closes. - **`text`** — a run of text, as written, and never empty, with its `ancestors` as `open` gives them. Entities are not decoded, and a `<` that opens no tag is part of the text, as the browser reads it. A comment ends a run, so `TO<!-- -->DO` arrives as two. It fires for the body of every element the browser reads as text too: `<script>`, `<style>`, `<textarea>`, `<title>`, `<iframe>`, `<noscript>`, `<noembed>`, `<noframes>`, `<xmp>` and `<plaintext>`. - **`close`** — `at` is where the element _started_, so it pairs with `open`. `hadText` says whether it held any non-whitespace. - **`end`** — every id on the page and where it was seen. Pass an array to run several. Findings from all of them are sorted into page order with the markup problems, so the list reads top to bottom whatever produced it. An entry that is not a function is left out, so `rules: [strict && house]` reads as it looks. Custom rule names are open-ended, so passing `rules` widens the result to `Finding<string>`. ::: tip This is a development-only surface It ships as nothing, so it can afford to be generous — and it is versioned more loosely than the renderer. A rule set that throws will take `check()` down with it. ::: ## check.enabled ```ts check.enabled; // true here, false in the production build ``` `check()` returns `[]` in the production build, so a suite that resolves it passes every assertion built on `check()` without looking at anything. Assert this once and it cannot: ```ts test('the checks are active', () => assert(check.enabled)); ``` See [confirming the dev build](/recipes/testing#confirm-the-dev-build). <!-- /api/create --> # @itsy/html/create ```ts import { createHtml, SCHEMES } from '@itsy/html/create'; import type { CreateOptions } from '@itsy/html/create'; ``` A separate `html` and `attrs`, with a different URL scheme list or whitespace rule. The root exports keep the defaults. ## createHtml ```ts createHtml(options?: CreateOptions): { html: typeof html; attrs: typeof attrs } ``` ```ts export const { html, attrs } = createHtml({ schemes: [...SCHEMES, 'sms'] }); ``` ::: warning Call it once, at module scope Each call has its own template cache. Calling `createHtml` inside a component re-scans every template on every render. Create it once and export the result. ::: ## CreateOptions ```ts interface CreateOptions { schemes?: Iterable<string>; // default SCHEMES collapse?: boolean; // default true } ``` ### schemes The allowed URL schemes, lowercase. It **replaces** the default set rather than adding to it. ```ts createHtml({ schemes: [...SCHEMES, 'sms'] }); // the defaults plus sms createHtml({ schemes: ['https'] }); // https and nothing else ``` ### collapse `false` keeps line breaks and indentation in the static markup exactly as written, instead of [collapsing them to single spaces](/guide/writing-html#whitespace). ```ts createHtml({ collapse: false }); ``` ## SCHEMES ```ts const SCHEMES: ReadonlySet<string>; // http, https, mailto, tel, data, blob ``` The default set, exported so it can be spread when needed. ::: warning `frame` and `wrap()` always use `SCHEMES`. A scheme added here is still blocked in a frame head entry or a `wrap()` attribute. For a single link, `raw()` on the whole tag is simpler — see [the URL guard](/security/url-guard#adding-a-scheme). ::: <!-- /api/frame --> # @itsy/html/frame ```ts import { frame, head, element } from '@itsy/html/frame'; import type { FrameOptions, HeadEntry, FramePart } from '@itsy/html/frame'; ``` ## frame ```ts frame(options: FrameOptions): Html ``` Writes a full HTML frame | option | type | notes | | ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `lang` | `string` | Required. `<html lang>`. Escaped. | | `title` | `string` | Required. Escaped. | | `description` | `string` | Escaped, placed right after the title. A head entry with the same name replaces it. | | `dir` | `'ltr' \| 'rtl' \| 'auto'` | `<html dir>`. | | `head` | `FramePart \| Iterable<FramePart>` | After charset, viewport, title and description. | | `header` | `Renderable` | Right after `<body>`. | | `content` | `Renderable` | Inside `<main id="maincontent" tabindex="-1">`. | | `main` | `boolean` | `false` writes `content` with no `<main>` wrapper. Default `true`. | | `footer` | `Renderable` | After `<main>`, before the scripts. | | `scripts` | `FramePart \| Iterable<FramePart>` | Right before `</body>`. | | `nonce` | `string` | Added to every script and style entry that has none. | | `attrs` | `{ html?, body?, main? }` | Extra attributes on the three elements the frame writes. `main` merges over the default `id` and `tabindex`. | ## head ```ts head(parts: FramePart | Iterable<FramePart>, options?: { nonce?: string }): Html ``` The merged head elements, with no `<head>` wrapper and none of the rest of the document. For a layout that writes `<html>` itself. ```ts html`<head>${head(parts, { nonce })}</head>`; ``` The merge is the same one `frame()` does, so a shared list of head assets behaves identically here. ## element ```ts element(entry: HeadEntry, nonce?: string): Html ``` One entry, rendered. ```ts run element({ tag: 'link', attrs: { rel: 'icon', href: '/icon.svg' } }); ``` Throws [code 17](/reference/errors#e17) for a tag name that is not legal, and [code 18](/reference/errors#e18) for a body on a void element. ## HeadEntry ```ts interface HeadEntry { tag: string; attrs?: Record<string, AttrValue>; body?: Renderable; key?: string; } ``` - `attrs` goes through [`attrs()`](/api/attrs), URL guard included — always the **default** guard, never one from `createHtml`. - `body` is escaped if it is text, called if it is a function. A `<script>` or `<style>` body must be `Html`, from `raw()`, or it is [code 6](/reference/errors#e6). - `key` overrides how the entry is identified for merging. `FramePart` is `HeadEntry | Html`. Ready-made `Html` is passed through untouched — not merged, not deduplicated, and not given a nonce. ## How entries merge Of two entries with the same identity, the later one wins and takes the earlier one's position. | tag | identity | | --------------------------------------------- | ---------------------------------------------- | | `title`, `base` | the tag; only one of each | | `meta` with `charset` | charset; only one | | `meta` | its `name`, else `property`, else `http-equiv` | | `link` with an icon `rel` | `rel` + `type` + `sizes` | | `link` with `rel="canonical"` or `"manifest"` | the rel; only one of each | | `link` | `rel` + `href` | | `script` with `src` | the `src` | | anything else | no identity; kept as many times as given | <!-- /api/html --> # @itsy/html ```ts import { html, trusted, attrs, cx, raw, Html, isHtml, HtmlError } from '@itsy/html'; import type { Renderable, AttrValue, AttrGroup, ClassValue, StyleValue } from '@itsy/html'; ``` ## html A template tag. Returns [`Html`](#html-class). ```ts html`<p class="${cls}">${text}</p>`; ``` Each value is escaped for the context it lands in. Throws [`HtmlError`](#htmlerror) on the first render of a template that breaks a rule. Values never throw except for [code 7](/reference/errors#e7). ### Contexts | context | treatment | | --------------------- | ----------------------------------------------------------- | | text | `&`, `<`, `>`, `"`, `'` escaped | | quoted attribute | the same escape | | URL attribute | the same escape, then [a scheme check](/security/url-guard) | | inside a tag | `attrs()` or `raw()` only | | right after `<` | `raw()` only: the browser reads a value there as a tag name | | `<script>`, `<style>` | `raw()` only | | comment | `raw()` only | - The scan reads only the static strings, so a value can never change which context it lands in. - It runs once per template, cached on the strings array, so a markup error throws on the first render and repeated renders do no extra work. - Unquoted attribute values and `on*` attributes are refused at scan time, whatever the value. - A `<script>` or `<style>` with a `<!--` or `<![CDATA[` still open does not end at its end tag: the browser may read that tag as text, so the scan keeps the block open, and a value after it is refused rather than escaped for a context it may not be in. ## trusted A template tag like `html`, without the escaping, for templates whose values are safe. ```ts const Nav = (links: Link[]) => trusted`<nav>${links.map((l) => trusted`<a href="${l.href}">${l.label}</a>`)}</nav>`; ``` On clean data it is [1.5 to 2.5 times faster](/reference/benchmarks#nothing-to-escape) than `html`. ## raw ```ts raw(markup: string): Html ``` Marks a string as HTML that is already safe. ```ts html`<div>${raw(sanitized)}</div>`; ``` ## Html {#html-class} The return type. A small wrapper around the markup, not a string. Keep it an `Html` while the page is being built, and take the string once, where it leaves the library: ```ts res.send(Page(data).markup); res.send(Page(data).render()); // the same, for those who read it as the last step ``` `String(view)` and `` `${view}` `` give the same string, but TypeScript works better with `.markup`. ::: warning Nest the `Html`, not its `.markup` In a template a string is text, so `.markup` is escaped a second time: ```ts html`<div>${view}</div>`; // <div><p>a < b</p></div> html`<div>${view.markup}</div>`; // <div><p>a < b</p></div> ``` `check()` and `frame()` take the `Html` too. ::: ### Handing it over Passed as-is, without `.markup`: | where | what happens | TypeScript error | | ----------------------------------------- | ------------------------------------------------------------ | ---------------- | | Express `res.send(view)` | sent as JSON, quotes included, even after `res.type('html')` | no | | Fastify `reply.send(view)`, `return view` | sent as JSON; after `reply.type('text/html')`, a 500 | no | | Koa `ctx.body = view` | sent as JSON, even with `ctx.type = 'html'` | no | | `node:http` `res.end(view)` | throws `ERR_INVALID_ARG_TYPE` | no | | Hono `c.html(view)` | works | yes | | `new Response(view)` | the markup, as `text/plain` unless the header says otherwise | yes | | `el.innerHTML = view` | works | yes | The frameworks that get it wrong type the body as `any`, so nothing flags it before a request does. Tested with Express 5.2, Fastify 5.12, Koa 3.2 and Hono 4.13. Everywhere else: | | | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `typeof view`, `if (view)` | `'object'`, and an empty one is truthy | | `assert.equal(view, str)` | fails: an object is never strictly equal to a string. Compare `view.markup` | | `structuredClone(view)`, `postMessage` | `{}`: the markup is in a private field and does not survive the copy. Send `view.markup` | | `console.log(view)` | `Html '<p>…</p>'` in the development build, `Html {}` in production | | `JSON.stringify({ view })` | gives the markup — there is a `toJSON` | | `Object.prototype.toString.call(view)` | `[object Html]` | | `${view}`, `view + ''`, `String(view)` | all go through one `Symbol.toPrimitive`, a nanosecond or so cheaper than the `toString` lookup they would otherwise do | The inspect hook is development-only — it is a debugging affordance, and the production build trades messages for bytes everywhere else too. A `#private` field makes TypeScript treat it as its own type, so a plain string will not pass where an `Html` is expected. `raw` and `html` are the only supported ways to create one. `instanceof` and [`isHtml`](#ishtml) both match on a realm-global brand rather than the prototype chain, so two copies of this library in one dependency tree still recognise each other's `Html`. Without that, a nested template from the other copy would be escaped as if it were text, silently. It is forgeable, but so is `raw()` — both need code already running in the process. ### Why it is not a `String` subclass It would be the obvious design, and it is a trap. Subclassing a builtin makes V8 give up the fast paths for `String.prototype` methods across the **entire process** — not just for the subclass, and not just for this library. `charCodeAt` alone gets about 9x slower, and the escaper calls it once per character. Merely declaring the class does it; no instance is needed. This library shipped that mistake and measured the cost: removing it made rendering 1.75x to 2.89x faster, and stopped penalising every other library in the process by up to 2.8x. JavaScriptCore shows no such penalty, so it is a V8 implementation choice rather than a cost the language requires. TC39 has a [proposal to remove builtin subclassing][rm-subclassing] for this family of reasons. [rm-subclassing]: https://github.com/tc39/proposal-rm-builtin-subclassing ## isHtml ```ts isHtml(value: unknown): value is Html ``` `true` for anything from `html` or `raw` - thus a plain string is `false`. ## HtmlError ```ts class HtmlError extends Error { name: 'HtmlError'; code: number; } ``` `code` is the same number in both development and production builds. In the development build `message` spells the problem out; in production it is `E<code>`. [See error codes here](/reference/errors). ## attrs and cx Re-exported from [`@itsy/html/attrs`](/api/attrs). ## Types `Renderable` is what a template accepts and the most common type to import. [See other types here](/reference/types). <!-- /api/util --> # @itsy/html/util ```ts import { join, map, range, when, choose, wrap, comment } from '@itsy/html/util'; ``` Opt-in helpers with no shared state, one export each, so a bundler keeps only what is imported. Everything except `comment` returns a plain array or the result of a thunk. Nothing here renders markup or escapes anything; the template it lands in does that, for the context it lands in. ## join ```ts join<I, J>(items: Iterable<I> | undefined, joiner: J): (I | J)[] ``` Puts `joiner` between the items. ```ts html`<p>${join(tags.map(Tag), ', ')}</p>`; ``` The joiner is a value like any other, so a string is escaped and an `Html` is not. `undefined` items give an empty array. ## map ```ts map<T>(items: Iterable<T> | undefined, f: (item: T, index: number) => Renderable): Renderable[] ``` `Array.prototype.map` for anything iterable, with an index. ```ts html`<ul>${map(ids, (id, i) => html`<li>${i}: ${id}</li>`)}</ul>`; ``` ::: tip This is for a `Set`, a `Map.values()` or a generator — things with no `.map` of their own. For an array, call `.map` and skip the import. ::: ## range ```ts range(end: number): number[] range(start: number, end: number, step?: number): number[] ``` The integers from `start` up to but not including `end`. One argument means `range(0, end)`. A negative step counts down. ```ts range(5); // [0, 1, 2, 3, 4] range(1, 10, 3); // [1, 4, 7] html`<p>${map(range(5), Star)}</p>`; ``` ## when ```ts when<T, F>(condition: unknown, trueFn: () => T, falseFn?: () => F): T | F | undefined ``` One branch or the other, and only the chosen branch is built. ```ts html`${when(user, () => Profile(user), () => Login())}`; ``` With no `falseFn`, a false condition renders nothing - so it is usually cleaner to just do `&&` in those cases. ## choose ```ts choose<T, V>(value: T, cases: readonly (readonly [T, () => V])[], fallback?: () => V): V | undefined ``` A `switch` as an expression. The first case that matches (strict equivalence) will be rendered. ```ts html`${choose(status, [ ['ok', () => Ok()], ['err', () => Err()], ], () => Unknown())}`; ``` ## wrap ```ts wrap(items: Iterable<Renderable>, tag: string, attributes?: Record<string, AttrValue>): Renderable[] ``` Each item inside a `<tag>`, with optional attributes. ```ts run html`<ul>${wrap(['a', 'b'], 'li', { class: 'name' })}</ul>`; ``` Items are rendered by the surrounding template, so text is escaped and `Html` is not. Attributes go through `attrs()` with the **default** URL guard, not one from `createHtml`. A tag name that is not a legal tag name throws [code 17](/reference/errors#e17). Inside `<script>` and `<style>` every item must itself be `Html`, and anything else throws [code 6](/reference/errors#e6): escaping keeps text from ending the block, but not from running. ## comment ```ts comment(text: string): Html ``` An HTML comment the text cannot close early. ```ts run html`${comment('closes early? --> no')}`; ``` <!-- /reference/agents --> --- title: For coding agents outline: [2, 2] --- <!--@include: ../../AGENTS.md--> --- This page is [AGENTS.md](https://github.com/itsyjs/html/blob/main/AGENTS.md) from the repository, included verbatim. It also ships inside the published package, so an agent working in a project that depends on `@itsy/html` will find it at `node_modules/@itsy/html/AGENTS.md`. Machine-readable summaries of this site are at [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt). <!-- /reference/benchmarks --> # Benchmarks These benchmarks are not intended to say one library is better than another, only to provide some rough idea of performance as a reference. To reproduce these tables: ```sh pnpm bench # the tables below pnpm bench:vs [rev] # this working tree against another revision, to check a change pnpm bench:size # bytes emitted rather than time ``` <small>All benchmark data below was produced on a base-model M5 Macbook Air</small> ## Relative speed @itsy/html is 1.00 in every column. Higher is faster, meaning 1.33 is a third faster and 0.25 is four times slower. | renderer | one `<a>` | one element | nested page | 1000 rows | escape-heavy | overall | | ----------------------------- | --------: | ----------: | ----------: | --------: | -----------: | ------: | | no escaping | 9.34 | 3.94 | 2.54 | 1.95 | 428.87 | 9.51 | | hand-written | 1.43 | 1.42 | 1.00 | 1.17 | 1.09 | 1.21 | | **@itsy/html** | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | | hono/html | 0.74 | 0.76 | 0.58 | 0.69 | 0.81 | 0.71 | | ghtml | 0.72 | 0.78 | 0.57 | 0.67 | 0.83 | 0.71 | | htm + preact-render-to-string | 0.34 | 0.28 | 0.28 | 0.25 | 1.23 | 0.39 | | lit + @lit-labs/ssr | 0.17 | 0.18 | 0.15 | 0.17 | 0.46 | 0.20 | ## Absolute time per render Lower is faster. | renderer | one `<a>` | one element | nested page | 1000 rows | escape-heavy | | ----------------------------- | --------: | ----------: | ----------: | --------: | -----------: | | no escaping | 12.1 ns | 44.3 ns | 0.96 µs | 102 µs | 0.01 µs | | hand-written | 78.5 ns | 123 ns | 2.45 µs | 168 µs | 2.15 µs | | **@itsy/html** | 113 ns | 174 ns | 2.45 µs | 198 µs | 2.35 µs | | hono/html | 153 ns | 230 ns | 4.22 µs | 286 µs | 2.92 µs | | ghtml | 156 ns | 224 ns | 4.28 µs | 296 µs | 2.83 µs | | htm + preact-render-to-string | 330 ns | 613 ns | 8.66 µs | 780 µs | 1.92 µs | | lit + @lit-labs/ssr | 657 ns | 953 ns | 16.3 µs | 1195 µs | 5.09 µs | ## html vs trusted performance [`trusted`](/api/html#trusted) is a more performant export that removes escaping | renderer | one `<a>` | one element | nested page | 1000 rows | plain text | overall | | ------------------------ | --------: | ----------: | ----------: | --------: | ---------: | ------: | | no escaping | 5.91 | 2.77 | 1.91 | 1.55 | 8.98 | 3.37 | | **@itsy/html `trusted`** | 2.12 | 1.62 | 1.71 | 1.48 | 2.53 | 1.86 | | hand-written | 2.26 | 2.00 | 1.30 | 1.34 | 1.72 | 1.69 | | **@itsy/html** | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 | | renderer | one `<a>` | one element | nested page | 1000 rows | plain text | | ------------------------ | --------: | ----------: | ----------: | --------: | ---------: | | no escaping | 12.4 ns | 44.8 ns | 0.90 µs | 96.5 µs | 6.06 ns | | **@itsy/html `trusted`** | 34.7 ns | 76.6 ns | 1.00 µs | 101 µs | 21.5 ns | | hand-written | 32.5 ns | 61.9 ns | 1.31 µs | 112 µs | 31.7 ns | | **@itsy/html** | 73.5 ns | 124 ns | 1.71 µs | 150 µs | 54.4 ns | ## Benchmark test descriptions Rendered from a list of 1000 products whose names hold `&` and `"`, and whose links hold `&` — ordinary data that still has to be escaped. | column | what it renders | | ------------ | ------------------------------------------------------------------ | | one `<a>` | a single link: one URL attribute, one class, one text value | | one element | one `<article>` with five values in it, no URL attribute | | nested page | a nav and a list, built from templates nested three deep | | 1000 rows | a table, 1000 rows of four cells, each row nesting a link template | | escape-heavy | 760 characters of nothing but `<`, `>`, `&`, `"` and `'` | The escape-heavy column is the worst case for an escaper, not a realistic page. Text with nothing to escape should be the fastest path for every renderer. ## The two reference points **hand-written** is a plain template literal with an `esc()` call around each value, using the same escaper @itsy/html uses. It has no scanner, no context, no URL guard and allocates no `Html`, so it is the 'speed floor' and not a typical performance example. **no escaping** is the same template literal with the `esc()` calls taken out. It is meant to be a reference for the absolute fastest the test machine is performing at. <!-- /reference/errors --> # Error codes `HtmlError.code` is the same number in every build. The development build writes the message out in full; the production build's message is `E` followed by the code. | code | meaning | from | | ---------- | ------------------------------------------------------------------------------- | -------------------------- | | [2](#e2) | an object or array for an attribute other than `class`, `style`, `aria`, `data` | `attrs` | | [3](#e3) | a refused attribute: anything starting with `on` | `html`, `attrs` | | [5](#e5) | an unquoted attribute value before an expression | `html` | | [6](#e6) | a non-`Html` expression inside a tag, `<script>`, `<style>` or a comment | `html`, `frame` | | [7](#e7) | a value that cannot be rendered: an object, a `Promise`, a symbol | `html` | | [8](#e8) | a tag never closed with `>` | `html` | | [9](#e9) | an element still open at the end, or one the next start tag closed implicitly | `html` | | [10](#e10) | an end tag that closes nothing, or the wrong element | `html` | | [11](#e11) | `/>` on an element that does not self-close | `html` | | [12](#e12) | an end tag on a void element | `html` | | [13](#e13) | nesting the browser rewrites | `html` | | [14](#e14) | the same attribute twice on one tag | `html` | | [15](#e15) | an id reference with no matching id | `check` | | [16](#e16) | an id used twice | `check` | | [17](#e17) | a bad tag name | `frame`, `element`, `wrap` | | [18](#e18) | a body on a void element | `frame`, `element` | | [19](#e19) | a URL the guard blocked | `check` | | [20](#e20) | a value `trusted` would write differently from `html` | `trusted` | Codes 1 and 4 are reserved. **When they happen.** Codes 2, 3, 5, 6 and 7 throw the first time a template runs. Codes 8 to 14 throw at the same moment, but only in the development build. Codes 15, 16 and 19 are never thrown — [`check()`](/api/check) returns them. Codes 17 and 18 throw whenever the offending entry is rendered. Code 20 throws only in the development build, whenever [`trusted`](/api/html#trusted) gets a value that `html` would escape or block. **What never throws.** Data. A hostile URL is replaced, hostile text is escaped, and neither stops the render. The one exception is `trusted` in the development build, whose job is to refuse a value that needs either. ## Code 2 {#e2} An object or array given for an attribute that does not take one. ```ts attrs({ title: { a: 1 } }); // ✗ attrs({ class: ['a', 'b'], style: { color: 'red' } }); // fine ``` Four keys take objects or arrays: `class`, `style`, `aria` and `data`. Everything else takes a string, number, bigint, boolean, `null` or `undefined`. ## Code 3 {#e3} An attribute starting with `on`, anywhere, with any value. ```ts html`<button onclick="${handler}">…</button>`; // ✗ attrs({ onclick: handler }); // ✗ ``` The value is code, so no escaping makes it safe — and that holds for `null` and for `Html` too, so the refusal is unconditional. Attach behaviour with `addEventListener`; see [in a browser](/recipes/client#behaviour-goes-on-with-a-listener). ::: warning The check is a prefix, so a custom element's `one` or `online` attribute is refused as well. A prefix is the only thing that can be relied on here. Rename the attribute, or write the whole tag inside `raw()`. ::: ## Code 5 {#e5} An expression in an attribute value with no quotes around it. ```ts html`<a href=${url}>…</a>`; // ✗ html`<a href="${url}">…</a>`; // fine ``` An unquoted value ends at the first whitespace, so a space anywhere in the value starts a new attribute. Escaping cannot fix that — the quotes have to be there. ## Code 6 {#e6} An expression that is not `Html` in a context where only markup can go. ```ts html`<input ${flag}>`; // ✗ inside a tag html`<script>${code}</script>`; // ✗ inside a script html`<!-- ${note} -->`; // ✗ inside a comment html`<${name}>`; // ✗ right after `<`, where the tag's name goes ``` Right after a `<` counts as inside a tag: a value that starts with a letter would be read as the tag's name, so `img src=x onerror=…` would open an `<img>` of its own. Write `<` for a literal less-than sign, or put a trusted tag name in `raw()`. A `<script>` or `<style>` with a `<!--` or `<. Inside `<script>`, `<style>` or a comment, use `raw()` — and read [data in a script block](/security/limits#data-in-a-script-block) before putting JSON there. For untrusted comment text, [`comment()`](/api/util#comment) escapes it safely. This is also the code a [`frame`](/api/frame) script or style entry throws when its body is a plain string rather than `Html`, and the one [`wrap()`](/api/util#wrap) throws for such an item in `<script>` or `<style>`: escaped text there still runs. ## Code 7 {#e7} A value with no sensible string form. ```ts html`<p>${{ a: 1 }}</p>`; // ✗ object html`<p>${fetchUser()}</p>`; // ✗ Promise ``` Await before building the template. For an object, pass the intended property. TypeScript reports this first: the parameter type is `Renderable`, so neither one typechecks. ## Code 8 {#e8} A tag that never reaches its `>`. ```ts html`<div class="a" <p>`; // ✗ ``` ::: details What the browser does Reads the `<p` as an attribute name on the `div`, producing one element with an attribute called `<p` and no paragraph at all. ::: ## Code 9 {#e9} An element still open when the template ends, or one that the next start tag closed implicitly. ```ts html`<div><p>x</p>`; // ✗ the div is never closed html`<ul><li>a<li>b</ul>`; // ✗ the second <li> closed the first ``` ::: details What the browser does An unclosed element swallows whatever follows it — in a list of components, the next sibling ends up inside the previous one. HTML does permit omitting `</li>`, `</p>` and some others, but in a template the likelier reading is that the end tag was forgotten. The browser closes more than the spec's list of omittable end tags: a `<p>` at any block such as `<xmp>` or `<listing>`, an `<option>` at an `<hr>`, a table cell, row or section at any table part that cannot sit in it. Each is reported where the parser does it. ::: To open in one template and close in another, say so with `raw()`: ```ts const open = html`${raw('<main class="page">')}<h1>${title}</h1>`; const close = html`${raw('</main>')}`; ``` ## Code 10 {#e10} An end tag closing the wrong element, or nothing at all. ```ts html`<b><i>x</b>`; // ✗ html`</p>`; // ✗ closes nothing ``` ::: details What the browser does Closes the wrong element, then re-opens what it had to close. A stray `</p>` makes the parser insert an empty `<p></p>`, which is why unexplained empty paragraphs turn up in rendered pages. ::: ## Code 11 {#e11} `/>` on an element that does not self-close. ```ts html`<div />`; // ✗ html`<my-element />`; // ✗ custom elements do not self-close either html`<br />`; // fine: void element ``` ::: details What the browser does Ignores the slash, opens the element, and never closes it. Everything after it ends up inside. `/>` does self-close inside `<svg>` and `<math>`, and the check follows that. ::: A formatter is a common cause — Prettier and oxfmt rewrite `<br>` to `<br />` inside templates unless [embedded formatting is turned off](/recipes/tooling#formatters-rewrite-embedded-markup). ## Code 12 {#e12} An end tag for an element that never has one. ```ts html`</br>`; // ✗ html`<img src="${url}"></img>`; // ✗ ``` ::: details What the browser does `</br>` inserts a second `<br>`. Other void end tags are ignored, so the markup is merely wrong rather than harmful. ::: ## Code 13 {#e13} Nesting the parser refuses to keep. ```ts html`<p><div>x</div></p>`; // ✗ html`<a href="${x}"><a href="${y}">…</a></a>`; // ✗ html`<table><tr><td>x</td></tr></table>`; // ✗ no tbody html`<table> total: <tr>…</tr></table>`; // ✗ text directly in a table html`<svg><p>x</p></svg>`; // ✗ an HTML tag that ends the SVG html`<body>…</body><script src="a.js"></script>`; // ✗ after </body> html`<div><tr><td>x</td></tr></div>`; // ✗ table parts outside a table html`<table><svg>…</svg></table>`; // ✗ anything but a table part, in a table html`<body><body class="x">…</body></body>`; // ✗ a second <body> ``` ::: details What the browser does Rewrites it. A `<div>` inside a `<p>` closes the paragraph first, leaving an empty `<p></p>` before the div and a stray `</p>` after it. A nested `<a>` is moved out. A `<tr>` with no `<tbody>` gets one inserted, so a CSS selector or a `querySelector` written against the source markup misses. Text directly inside a table is moved out in front of it. Inside SVG or MathML, an HTML tag such as `<p>`, `<div>` or `<img>` closes the foreign content and starts over as HTML. Anything after `</body>` is moved back into the body, and anything that belongs in the head, after `</head>`, back into the head. A `<tr>`, `<td>` or other table part outside a table is dropped, with its text kept. A second `<html>` or `<body>` is dropped and its attributes added to the first, and a `<head>` after the head is dropped. ::: ## Code 14 {#e14} The same attribute written twice on one tag. ```ts html`<a class="a" class="b">…</a>`; // ✗ ``` ::: details What the browser does Keeps the first and discards the second, silently — usually the opposite of what was intended, since the later one is normally the override. ::: ## Code 15 {#e15} An id reference that points at no id on the page. Reported by [`check()`](/api/check) only, since a single template cannot see the whole page. ```ts html`<label for="email">Email</label>`; // ✗ if no element has id="email" ``` Checked on `for`, `form`, `list`, `headers`, `popovertarget`, `commandfor`, `itemref` and the `aria-*` relations. A broken `for` means clicking the label does nothing and the input has no accessible name. Pass `check(markup, { ids: false })` when checking a fragment whose references point outside it. ## Code 16 {#e16} The same id on two elements. `check()` only. ```ts html`<div id="main"></div><div id="main"></div>`; // ✗ ``` Every id reference then resolves to the first, and `getElementById` returns the first. ## Code 17 {#e17} A tag name that is not a legal tag name, where a tag is built from a string. ```ts wrap(names, 'li li'); // ✗ element({ tag: '<script>' }); // ✗ ``` A legal name starts with a letter and continues with letters, digits, `-` or `_`. This is the guard on the places that take a tag name as data: [`wrap()`](/api/util#wrap), [`element()`](/api/frame#element) and `frame` entries. ## Code 18 {#e18} A body on an element that cannot have one. ```ts element({ tag: 'meta', attrs: { charset: 'utf-8' }, body: 'x' }); // ✗ ``` Void elements — `meta`, `link`, `br`, `img` and the rest — have no end tag, so there is nowhere for a body to go. ## Code 19 {#e19} A URL [the guard](/security/url-guard) replaced with `about:blank#blocked`. Reported by [`check()`](/api/check), never thrown, because the URL came from data rather than from the template. ```ts check(String(html`<a href="${'javascript:alert(1)'}">x</a>`)); // [{ code: 19, … }] ``` Finding one means something upstream produced a URL with a scheme outside the allowed set. Either the data is wrong, or the scheme should be allowed — see [adding a scheme](/security/url-guard#adding-a-scheme). ## Code 20 {#e20} A value [`trusted`](/api/html#trusted) would write differently from `html`. Development build only. ```ts trusted`<p>${'Tom & Jerry'}</p>`; // ✗ html writes Tom & Jerry trusted`<a href="${'javascript:x'}">x</a>`; // ✗ the guard would block it ``` In production `trusted` writes every value as it is. The development build refuses any value that `html` would escape or block, so production never writes something `html` would not. Use `html` for a template that takes this value. <!-- /reference/imports --> # Import map Six entry points. Each is its own module, so a bundler keeps only what is imported. | import | exports | | ---------------------------------- | ---------------------------------------------------------------------- | | `@itsy/html` | `html`, `trusted`, `attrs`, `cx`, `raw`, `Html`, `isHtml`, `HtmlError` | | [`@itsy/html/attrs`](/api/attrs) | `attrs`, `cx`, `esc` — no template scanner | | [`@itsy/html/check`](/api/check) | `check` — the markup and accessibility checks | | [`@itsy/html/frame`](/api/frame) | `frame`, `head`, `element` | | [`@itsy/html/util`](/api/util) | `join`, `map`, `range`, `when`, `choose`, `wrap`, `comment` | | [`@itsy/html/create`](/api/create) | `createHtml`, `SCHEMES` | `@itsy/html/frame` includes the renderer, so a page that uses `frame()` does not need to import `@itsy/html` separately. `@itsy/html/util` has no shared state between its helpers, so importing `join` does not pull in the other six. Types come from the entry point they belong to: `Renderable` and the `attrs()` types from the root, `Problem`, `Finding`, `RuleSet`, `Visitor`, `Report`, `A11yRule`, `A11yOptions` and `CheckOptions` from `/check`, `FrameOptions`, `HeadEntry` and `FramePart` from `/frame`, `CreateOptions` from `/create`. They are listed in [types](/reference/types). ## Two builds per entry `package.json` declares a `development` export condition for all six. Bundlers that honour it — Vite does, automatically — get the development build during development and the production build in a production build. Node and esbuild need `--conditions=development`. See [bundlers and editors](/recipes/tooling). Both builds render identical output and throw the same `HtmlError.code`. The one exception is [`trusted`](/api/html#trusted): its development build refuses every value on which the two would differ, with [code 20](/reference/errors#e20). Only the message text and the markup check differ: the development build spells the message out and checks the markup, and the production build throws `E` followed by the code. <!-- /reference/types --> # Types Every export is typed in its `.d.ts`; this is the shape of the ones most likely to be written out. ## `Renderable` ```ts type Renderable = | string | number | bigint | boolean | null | undefined | Html | Iterable<Renderable> | (() => Renderable); ``` What a template accepts, and therefore the type to give a [slot](/guide/writing-html#slots). Objects and promises are absent deliberately, so `${user}` is a type error rather than `[object Object]`, and an un-awaited promise fails to compile rather than rendering as nothing. From `@itsy/html`. ## `AttrValue` ```ts type AttrValue = | string | number | bigint | boolean | null | undefined | ClassValue[] // class | StyleValue // style | AttrGroup; // aria, data ``` A value for [`attrs()`](/api/attrs). `true` gives a bare attribute, `false` and nullish leave it out — except for `aria-*`, `draggable`, `spellcheck` and `contenteditable`, where booleans render `"true"` and `"false"`. ## `ClassValue` ```ts type ClassValue = | string | number | bigint | boolean | null | undefined | ClassValue[] | Record<string, unknown>; ``` What [`cx()`](/api/attrs#cx) takes, and what the `class` key in `attrs()` takes. Arrays nest, objects contribute the keys whose value is truthy, and falsy values are skipped. ## `StyleValue` ```ts type StyleValue = Record<string, string | number | null | undefined | false>; ``` A `style` attribute as an object. Keys are written out exactly as given — `--brand`, `background-color` — with no camelCase conversion. `null`, `undefined` and `false` drop the declaration. ## `AttrGroup` ```ts type AttrGroup = Record<string, string | number | bigint | boolean | null | undefined>; ``` The object form of `aria` and `data`, so `aria: { expanded: open }` becomes `aria-expanded="…"`. ## `Problem` ```ts interface Problem { code: number; message: string; at: number; near: string; } ``` What [`check()`](/api/check) returns, one per problem, in page order. `at` is a character offset; in a template a `${…}` counts as those four characters. From `@itsy/html/check`, along with `CheckOptions`. ## `Finding` ```ts interface Finding<R extends string = string> { rule: R; message: string; at: number; near: string; } ``` What a rule reports, mixed into the same list as `Problem` by [`check()`](/api/check). Names, not numbers: these are not [`HtmlError` codes](/reference/errors), and nothing here ever throws. Tell the two apart with `'rule' in p`. From `@itsy/html/check`. `A11yRule` is the union of the twenty-five names the built-in accessibility rules can report. `check(markup)` returns `Finding<A11yRule>`, so a comparison against a name that does not exist is a type error rather than a test that never matches, and `a11y: { without: [...] }` checks its entries the same way. That object is `A11yOptions`, also from `@itsy/html/check`. ## `RuleSet`, `Visitor`, `Report` ```ts type RuleSet = (report: Report) => Visitor; type Report = (rule: string, message: string, at: number) => void; interface Visitor { open?: (tag: string, attrs: ReadonlyMap<string, string>, at: number, ancestors: readonly string[]) => void; text?: (content: string, at: number, ancestors: readonly string[]) => void; close?: (tag: string, at: number, hadText: boolean) => void; end?: (ids: ReadonlyMap<string, number>) => void; } ``` A project's own rules, for `check()`'s [`rules`](/api/check#custom-rules) option. Every hook is optional. From `@itsy/html/check`. Passing custom rules widens the result to `Finding<string>`, since this cannot know their names. ## `FrameOptions`, `HeadEntry`, `FramePart` From `@itsy/html/frame`; the fields are listed in [the frame API](/api/frame). `FramePart` is `HeadEntry | Html`, which is what `head` and `scripts` accept. ## `CreateOptions` ```ts interface CreateOptions { schemes?: Iterable<string>; collapse?: boolean; } ``` From [`@itsy/html/create`](/api/create). <!-- /playground --> --- title: Playground --- # Playground Everything below runs in this page. The library is synchronous and has no dependencies, so the same code that renders on a server renders here. <ClientOnly> <Playground /> </ClientOnly> ## What to try - Put `<` or `&` in a piece of text and watch it come back escaped. - Change a `javascript:` URL to `https:` and back. It is never an error, only a replacement. - Delete a closing tag and see which error code comes back, and what the message says the browser would do. - Give two elements the same id. The template check says nothing; `check()` finds it, because only a finished page can know. - Swap `aria-pressed` for `data-pressed` and set it to `false`. One renders, one disappears — see [attributes](/guide/writing-html#attributes). - Write a `<style>` block and style the markup. The preview renders in a shadow root, so it starts from the browser's own stylesheet rather than this site's, and nothing written there can reach the rest of this page.