@jangxyz/html-tagged-templates

HTML tagged templates

Build DOM HTML elements with html`` tagged templates, plus more. No dependencies.

import { html } from '@jangxyz/html-tagged-templates'

const element = html`<div>Let's go JavaScript</div>`

console.log(element intanceof HTMLElement) // true
console.log(element.textContent) // "Let's go JavaScript"

Install

npm install @jangxyz/html-tagged-templates

NOTE Before it reaches v1.0, it is considered unstable, meaning the APIs are not fixed and may due to change. If you are thinking of trying out, please verify the version you are using and the corresponding documentation.

Usage

You can nest elements.

html`<div>
  I am an element, and this is a 
  ${html`<button>button</button>`}
</div>`

Pass in attributes, including event callbacks.

const checkbox = html`<input 
  type="checkbox" 
  checked="${true}" 
  onchange="${(event) => {
    console.log("change:", event.target.checked);
  }}"
/>`

Note all attributes should be surrounded with quotes -- both single and double quotes are allowed.

Types

By default the html`` tagged template returns an HTMLElement.
If you want it to return the exact element, like if you want html`` to return an object of type HTMLInputElement, you can use the raw htmlSingleFn function below. We would like to support this to html`` too, but currently there is a limit in TypeScript that prevents from doing this.
Meanwhile you can pass the type or the name of the tag as a generic:

const checkbox0 = html`<input type="checkbox" />`                      // HTMLElement by default
//    ^? const checkbox0: HTMLElement

const checkbox1 = html<HTMLInputElement>`<input type="checkbox" />`    // pass generic type, or
//    ^? const checkbox1: HTMLInputElement

const checkbox2 = html<'input'>`<input type="checkbox"  />`            // pass the name of the tag
//    ^? const checkbox2: HTMLInputElement

const checkbox3 = html`<input type="checkbox" />` as HTMLInputElement  // use type assertion
//    ^? const checkbox3: HTMLInputElement

Others

In case you feel tagged template literals is too limited, you can use the functions underneath directly, as it providers more features.

htmlSingleFn

import { htmlSingleFn } from '@jangxyz/html-tagged-templates'

const tdEl = htmlSingleFn("<td>Hi there</td>")

const trEl = htmlSingleFn(`<tr>
  <td>cell 1</td>
  <td>cell 2</td>
</tr>`)

To access elements inside nested the outermost element, see htmlTuplefn.

Multiple string arguments result into a single element. You can pass in attributes values, including event callbacks.

const button = htmlSingleFn([
  '<button type="button" aria-pressed="', false, '" onclick="',
    (event) => console.log("click"),
  '">Click me</button>' 
])

htmlTupleFn

htmlTupleFn recieves a query option which returns an object with the queried results. The result is a tuple, where the first item is the outermost element and the second item is composed of each query options' results.

import { htmlTuplefn } from '@jangxyz/html-tagged-templates'

const result = htmlTuplefn('<ul><li>first item</li><li>second item</li><ul>', {
  query   : { firstItem: 'li:first-of-type' },  // invokes .querySelector()
  queryAll: { items: 'li' }                     // invokes .queyrSelectorAll()
})

const [ulEl, { firstItem, items }] = result

console.log(firstItem.textContent) // 'first item'
console.log(items.length) // 2

In case both query and queryAll option uses the same name, only the result from query remains.

const [ulEl, { item }] = htmlTuplefn('<ul><li>first item</li><li>second item</li><ul>', {
  query   : { item: 'li' },
  queryAll: { item: 'li' },
})

console.log(item instanceof HTMLLIElement)

Apart from the fact that the result is a tuple, everything else is same with htmlSingleFn.

htmlMultipleFn

In case you want to return multiple elements at once.

import { htmlMultipleFn } from '@jangxyz/html-tagged-templates'

const [divEl, pEl] = htmlMultipleFn(["<div>Hi there,</div>", "<p>I am here</p>"])