html

Assemble a template string with a JavaScript tagged template literal.

htmlUtilities

Assemble a template string with a JavaScript tagged template literal.

Overview

The html function in Regor is a utility function for creating HTML strings using template literals and interpolating values into the resulting string. It is commonly used to generate HTML content dynamically within Regor components.

Try it live

From strings to structured DOMLive API

Live preview

Text to encode

HTML / RAW TAGS

<p>Hello, Regor</p>

raw produces the same string: true

SVG TAG

<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8"/></svg>

JSON TEMPLATE

{
  "t": "p",
  "c": [
    {
      "d": "Hello, Regor"
    }
  ]
}

ROUND TRIP

Convert the JSON to a fragment, then back to JSON.

Generated strings are shown as text. Tagged templates assemble strings; they do not sanitize interpolated values.

templates.ts

import {
  computed,
  html,
  raw,
  ref,
  svg,
  toFragment,
  toJsonTemplate,
} from 'regor'

export function createTemplates(interactive = false) {
  const message = ref('Hello, Regor')
  const json = computed(() => ({ t: 'p', c: [{ d: message() }] }))
  const serialized = computed(() => JSON.stringify(json(), null, 2))
  const tagged = computed(() => html`<p>${message()}</p>`)
  const rawTagged = computed(() => raw`<p>${message()}</p>`)
  const svgTagged = svg`<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8"/></svg>`
  const roundTrip = ref('Convert the JSON to a fragment, then back to JSON.')
  const convert = () => {
    const fragment = toFragment(json())
    const element = fragment.firstElementChild!
    roundTrip(JSON.stringify(toJsonTemplate(element), null, 2))
  }
  return {
    interactive,
    message,
    serialized,
    tagged,
    rawTagged,
    svgTagged,
    roundTrip,
    convert,
  }
}

export const templatesTemplate = html` <div class="guide-demo">
  <div class="guide-controls">
    <label for="template-message">Text to encode</label
    ><input
      id="template-message"
      type="text"
      maxlength="60"
      r-model="message"
      :value="message"
      :disabled="!interactive"
    /><button type="button" @click="convert" :disabled="!interactive">
      JSON → fragment → JSON
    </button>
  </div>
  <div class="directive-zones">
    <article class="directive-card">
      <span class="guide-kicker">HTML / RAW TAGS</span>
      <pre class="api-snapshot" r-text="tagged"></pre>
      <p>raw produces the same string: {{ tagged === rawTagged }}</p>
      <span class="guide-kicker">SVG TAG</span>
      <pre class="api-snapshot" r-text="svgTagged"></pre>
    </article>
    <article class="directive-card">
      <span class="guide-kicker">JSON TEMPLATE</span>
      <pre class="api-snapshot" r-text="serialized"></pre>
      <span class="guide-kicker">ROUND TRIP</span>
      <pre class="api-snapshot" r-text="roundTrip"></pre>
    </article>
  </div>
  <p class="guide-hint">
    Generated strings are shown as text. Tagged templates assemble strings; they
    do not sanitize interpolated values.
  </p>
</div>`

browser.ts

import { createApp, RegorConfig, useScope } from 'regor'
import { apiExamples } from './examples'

const element = document.getElementById('api-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(apiExamples, name)) {
  const example = apiExamples[name as keyof typeof apiExamples]
  const scope = useScope<object>(() => example.create(true))
  const config =
    'config' in scope.context && scope.context.config instanceof RegorConfig
      ? scope.context.config
      : undefined
  createApp(scope, { element, template: example.template }, config)
}

Edit the text, then convert a JSON template into a detached fragment and serialize its element back to JSON.

Usage

Creating HTML Strings

The html function takes two parameters:

templates (TemplateStringsArray): An array of string literals representing the static parts of the HTML template.
...args (any[]): Any number of additional arguments that will be interpolated into the template to generate the dynamic parts of the HTML.

Example

import { html } from 'regor'

// Create an HTML string with dynamic content
const name = 'John'
const age = 30
const htmlString = html`<p>
  Hello, my name is ${name} and I am ${age} years old.
</p>`

// The resulting HTML string:
// "<p>Hello, my name is John and I am 30 years old.</p>"

Parameters

templates (TemplateStringsArray): An array of string literals representing the static parts of the HTML template.
...args (any[]): Any number of additional arguments that will be interpolated into the template to generate the dynamic parts of the HTML.

Return Value

Returns a string that represents the HTML content generated by interpolating the template literals and values provided in the args array.

String interpolation is separate from reactive binding

JavaScript interpolation runs when the string is assembled. Regor expressions such as {{ message }} are bound when the template mounts.

Notes

The html function is useful for creating HTML strings with dynamic content, such as when generating HTML markup for Regor components or templates.
It uses JavaScript's template literal syntax to define the static parts of the HTML template and interpolates values into the template using ${...} placeholders.
The resulting HTML string can be directly used in your Regor components or inserted into the DOM as needed.
In Regor, this function is commonly used in conjunction with template rendering and component creation to generate HTML content.