HTML Templates

The @microsoft/fast-element module offers a named export html which is a tag template literal. It can be used to create HTML snippets which will become your web components shadow DOM.

Example:

import { html } from "@microsoft/fast-element";

export const template = html`
  <template>Hello world</template>
`;

Binding

When working with the html template, bindings allow more complex behavior than simply passing attributes. These bindings are dynamic and are denoted by the arrow function. By default attributes are assumed to be strings. We typically denote x for the element, and c for the context.

Example:

import { attr, FASTElement, html } from '@microsoft/fast-element';

const template = html<NameTag>`
  <h3>${x => x.greeting.toUpperCase()}</h3>
`;

export class NameTag extends FASTElement {
  @attr
  greeting: string = 'hello';
}

NameTag.define({
  name: 'name-tag',
  template
});

When the greeting attribute is updated, so will the template.

Content

To bind the content of an element, simply provide the expression within the start and end tags of the element. It can be the sole content of the element or interwoven with other elements and text.

Example: Basic Text Content

<h3>${x => x.greeting.toUpperCase()}</h3>

Example: Interpolated Text Content

<h3>${x => x.greeting}, my name is ${x => x.name}.</h3>

Example: Heterogeneous Content

<h3>
  ${x => x.greeting}, my name is
  <span class="name">${x => x.name}</span>.
</h3>

Note

Dynamic content is set via the textContent HTML property for security reasons. You cannot set HTML content this way. See the Properties binding section for the explicit, opt-in mechanism for setting HTML via :innerHTML.

Booleans

Boolean bindings use the ? symbol, use these for Boolean attributes.

Example:

import { html } from "@microsoft/fast-element";

export const template = html`
  <button
    ?disabled="${(x) => x.disabled}"
  >
    Button
  </button>
`;

Events

Events bindings use the @ symbol. All Element events are available see the MDN documentation for details.

Example:

import { html } from "@microsoft/fast-element";

export const template = html`
  <button
    @click="${(x, c) => x.clickHandler(c.event)}"
  >
    Button
  </button>
`;

Important

After your event handler is executed, preventDefault() will be called on the event object by default. You can return true from your handler to opt-out of this behavior.

Properties

Property bindings use the : symbol.

Example:

import { html } from "@microsoft/fast-element";

export const template = html`
  <input
    :value="${(x) => x.value}"
  />
`;

Some complex use cases include binding to a custom property, updating that property and observing it. To learn more about observing properties, check out the FASTElement document.

Typed Templates

Your templates can be typed to the data model that they are rendering over. In TypeScript, we provide the type as part of the tag: html<NameTag>.

import { html } from '@microsoft/fast-element';

const template = html<NameTag>`
  <div>${x => x.greeting}</div>
`;