---
name: remix-templating
description: Server-side HTML templating in Remix v3 via `remix/html-template` — the `` html`...` `` tagged template literal with automatic XSS-safe escaping, `html.raw` for trusted fragments, composable `SafeHtml` branded values, the `isSafeHtml` type guard, and integration with `createHtmlResponse` from `remix/response/html` for endpoints that return HTML without spinning up the JSX runtime. Load whenever the user is building HTML responses without JSX (webhooks, RSS feeds, sitemaps, email bodies, OG/Twitter previews, HTMX fragments, server-rendered snippets), generating safe HTML from user input, composing reusable HTML helpers, deciding when to use JSX vs templates, or about to install `handlebars`, `ejs`, `mustache`, `pug`, `nunjucks`, `lit-html`, `escape-html`, `xss`, `sanitize-html`, `dompurify` (for server output). For full-page interactive UIs, use /remix:ui (JSX) instead.
---
# Templating
`remix/html-template` is a safe-by-default tagged template literal for building HTML strings. Use it when you want to return HTML without spinning up the JSX runtime — small endpoints, email bodies, RSS feeds, snippets sent to HTMX-style clients.
## Imports
```ts
import { html, isSafeHtml, type SafeHtml } from 'remix/html-template'
import { createHtmlResponse } from 'remix/response/html'
```
## XSS-safe by default
```ts
const userInput = ''
const greeting = html`
Hello ${userInput}!
`
String(greeting)
// → '
Hello <script>alert("XSS")</script>!
'
```
Every interpolated value is escaped. You don't have to remember.
## Composing fragments
`SafeHtml` values nested into another `html` template don't get double-escaped:
```ts
const title = html`
My Title
`
const para = html`
Hello ${userName}
`
const page = html`
${title}
${para}
`
```
The branded `SafeHtml` type tells `html` "I'm already safe, don't escape me again."
## `html.raw` — when you know it's trusted
For pre-escaped HTML or trusted assets (e.g. an SVG icon you control):
```ts
const icon = '' // from your codebase, not user input
const button = html.raw``
```
**Never** use `html.raw` with user input or any value that traversed the network.
## Returning HTML from an action
Pair with `createHtmlResponse` from `remix/response/html`:
```ts
import { createHtmlResponse } from 'remix/response/html'
export function contactPage(ctx: RequestContext) {
return createHtmlResponse(html`
Contact
Contact us
`)
}
```
`createHtmlResponse` sets `Content-Type: text/html; charset=utf-8` and accepts a `SafeHtml`, plain string, or `ReadableStream`.
## Arrays interpolate cleanly
```ts
const items = ['apple', 'banana', 'cherry']
const list = html`
${items.map((item) => html`
${item}
`)}
`
```
Arrays of `SafeHtml` are joined without separators. Use `.join('')` only if you specifically need a separator.
## When to use JSX vs `html`
| Use JSX (`remix/ui`) when... | Use `html` template when... |
|---|---|
| Multi-page app with shared `Document` shell | One-off HTML responses (webhooks, emails, RSS) |
| Components compose visually | Output is template-shaped, no component tree |
| You want client hydration | Server-only render, no JS |
| You want the two-phase setup/render model | You're building a string |
Both can coexist — a JSX page can include `html.raw\`...\`` for a trusted snippet; an `html`-based response can read from helpers that return `SafeHtml`.
## Type guard
```ts
function render(value: unknown) {
if (isSafeHtml(value)) {
return createHtmlResponse(value)
}
return new Response(String(value), { headers: { 'Content-Type': 'text/plain' } })
}
```
## Further reading
- [`references/safe-html.md`](./references/safe-html.md) — full escape semantics, composition rules, common patterns
- See also: [ui](../ui/SKILL.md) for JSX, [controllers](../controllers/SKILL.md) for the action context, [security](../security/SKILL.md) for `getCsrfToken`