Raw

Marks a string as trusted HTML, bypassing escaping when interpolated inside html. Use it when you need to inject markup you fully control — icons, pre-rendered fragments, or server-sanitized content.

Basic usage

import { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml, const raw: (value: string) => RawHtmlraw } from "ilha";

const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<div>${function raw(value: string): RawHtmlraw("<em>hello</em>")}</div>`;
// → <div><em>hello</em></div>

Without raw(), the same string would be escaped:

import { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml } from "ilha";

const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<div>${"<em>hello</em>"}</div>`;
// → <div>&lt;em&gt;hello&lt;/em&gt;</div>

When to use it

raw() is appropriate when the markup comes from a source you fully control:

import const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>, Record<string, never>> & {
    html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtml;
    raw: (value: string) => RawHtml;
    mount: (registry: IslandRegistry, options?: MountOptions) => MountResult;
    from: <TInput, TStateMap extends Record<string, unknown>>(selector: string | Element, island: Island<TInput, TStateMap>, props?: Partial<TInput>) => (() => void) | null;
    context: <T>(key: string, initial: T) => ContextSignal<...>;
}
ilha, { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml, const raw: (value: string) => RawHtmlraw } from "ilha";

// SVG icons defined in your codebase
const const chevron: "<svg viewBox=\"0 0 16 16\">\n    <path d=\"M4 6l4 4 4-4\"/>\n</svg>"chevron = `<svg viewBox="0 0 16 16">
    <path d="M4 6l4 4 4-4"/>
</svg>`;

const const Dropdown: Island<Record<string, unknown>, Record<string, never>>Dropdown = const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>, Record<string, never>> & {
    html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtml;
    raw: (value: string) => RawHtml;
    mount: (registry: IslandRegistry, options?: MountOptions) => MountResult;
    from: <TInput, TStateMap extends Record<string, unknown>>(selector: string | Element, island: Island<TInput, TStateMap>, props?: Partial<TInput>) => (() => void) | null;
    context: <T>(key: string, initial: T) => ContextSignal<...>;
}
ilha
  .IlhaBuilder<Record<string, unknown>, Record<string, never>, Record<string, never>>.render(fn: (ctx: RenderContext<Record<string, unknown>, Record<string, never>, Record<string, never>>) => string | RawHtml): Island<Record<string, unknown>, Record<string, never>>render(() => const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<button>Options ${function raw(value: string): RawHtmlraw(const chevron: "<svg viewBox=\"0 0 16 16\">\n    <path d=\"M4 6l4 4 4-4\"/>\n</svg>"chevron)}</button>`);

import { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml, const raw: (value: string) => RawHtmlraw } from "ilha";

// Pre-rendered HTML from a trusted server-side renderer
const const renderedMarkdown: "<h1>Title</h1><p>Body text.</p>"renderedMarkdown = `<h1>Title</h1><p>Body text.</p>`;

const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<article>${function raw(value: string): RawHtmlraw(const renderedMarkdown: "<h1>Title</h1><p>Body text.</p>"renderedMarkdown)}</article>`;

When not to use it

Never pass user input to raw(). It disables all escaping, so any unescaped string becomes a potential XSS vector:

import { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml, const raw: (value: string) => RawHtmlraw } from "ilha";

// ❌ Never do this
const const userComment: "<script>alert(1)</script>"userComment = `<script>alert(1)</script>`;
const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<p>${function raw(value: string): RawHtmlraw(const userComment: "<script>alert(1)</script>"userComment)}</p>`;

// ✅ Do this instead — html`` escapes it automatically
const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<p>${const userComment: "<script>alert(1)</script>"userComment}</p>`;

Composing with `html`

html results are already treated as safe and pass through unescaped without needingraw(). Reserve raw() for plain strings that contain trusted markup:

import { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml, const raw: (value: string) => RawHtmlraw } from "ilha";

// html`` result — no raw() needed
const const badge: RawHtmlbadge = const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<span class="badge">New</span>`;
const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<div>${const badge: RawHtmlbadge}</div>`;

// Plain string with markup — raw() required
const const iconStr: "<svg>…</svg>"iconStr = `<svg>…</svg>`;
const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<div>${function raw(value: string): RawHtmlraw(const iconStr: "<svg>…</svg>"iconStr)}</div>`;

Return type

raw() returns a RawHtml object — the same type produced by html. This means raw values compose freely with nested templates and arrays:

import { const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml, const raw: (value: string) => RawHtmlraw } from "ilha";

const const icons: string[]icons = ["<svg>…</svg>", "<svg>…</svg>"];

const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`
  <ul>
    ${const icons: string[]icons.Array<string>.map<RawHtml>(callbackfn: (value: string, index: number, array: string[]) => RawHtml, thisArg?: any): RawHtml[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn  A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg  An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.map((icon: stringicon) => const html: (strings: TemplateStringsArray, ...values: unknown[]) => RawHtmlhtml`<li>${function raw(value: string): RawHtmlraw(icon: stringicon)}</li>`)}
  </ul>
`;

Notes

raw() only has an effect inside html. Outside of a template it simply wraps the string in a RawHtml object with no other transformation.
There is no runtime sanitization inside raw(). If you need to accept user-generated HTML, sanitize it with a dedicated library such as DOMPurify before passing it to raw().

#Raw

#Basic usage

#When to use it

#When not to use it

#Composing with html

#Return type