Template API reference for the Template class in Semantic UI Templating file-text API Reference
Categories

Template

The Template class represents a compiled template and provides methods for manipulating and rendering it. It integrates with the Semantic UI component system and supports various rendering engines.

Semantic UI ships with a native rendering engine by default, which renders templates directly to DOM. An optional Lit engine compiles templates to lit html and is available when imported and registered explicitly.

Advanced Use Only When using Semantic UI components, a template will automatically be created from defineComponent. It is not recommended to use Template class on its own except for advanced use-cases.

Constructor

Syntax

new Template(options)

Parameters

NameTypeDescription
optionsObjectConfiguration options for the template

Options

NameTypeDescription
templateNamestringName of the template
astObject[]Compiled AST of the template
templatestringThe template string
dataObjectInitial data for the template
elementElementThe DOM element associated with the template
renderRootElementThe root element for rendering
cssstringCSS styles associated with the template
eventsObjectEvent handlers for the template
keysObjectKey bindings for the template
defaultStateObjectConfiguration for reactive state
subTemplatesObjectSub-templates used within this template
createComponentFunctionFunction to create the component instance
parentTemplateTemplateThe parent template when nested
renderingEnginestringThe rendering engine to use (default: ‘native’)
isPrototypebooleanWhether this is a prototype template
attachStylesbooleanWhether to attach styles to the renderRoot
onCreatedFunctionCallback when the template is created
onRenderedFunctionCallback when the template is rendered
onDestroyedFunctionCallback when the template is destroyed
onThemeChangedFunctionCallback when the theme changes

Usage Examples

Basic Initialization with Template String

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b>',
  data: { name: 'John' }
});

Initialization with AST

import { TemplateCompiler } from '@semantic-ui/compiler';
import { Template } from '@semantic-ui/templating';


const compiler = new TemplateCompiler('Welcome <b>{name}</b>');
const ast = compiler.compile();


const template = new Template({
  templateName: 'greet-user',
  ast,
  data: { name: 'John' }
});

Advanced Initialization

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'user-profile',
  template: `
    <div class="user-profile">
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <button class="update">Update</button>
    </div>
  `,
  data: { user: { name: 'John Doe', email: 'john@example.com' } },
  events: {
    'click .update': ({ self }) => self.updateUser()
  },
  defaultState: {
    user: { name: 'John Doe', email: 'john@example.com' }
  },
  createComponent: ({ state }) => ({
    updateUser() {
      state.user.set({ name: 'Jane Doe', email: 'jane@example.com' });
    }
  }),
  onRendered: () => console.log('User profile rendered'),
  attachStyles: true,
  css: `
    .user-profile {
      padding: 20px;
      border: 1px solid #ccc;
    }
  `
});

Methods

initialize

Initializes the template, setting up reactive state and event handlers.

Syntax

template.initialize()

Usage

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b>',
  data: { name: 'John' }
});


template.initialize();

render

Renders the template with the current data.

Syntax

template.render(additionalData)

Parameters

NameTypeDescription
additionalDataObjectAdditional data to merge for rendering

Returns

The rendered template content. The shape depends on the rendering engine — DOM nodes for native, a TemplateResult for lit.

Usage

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b>',
  data: { name: 'John' }
});


const rendered = template.render({ title: 'Hello' });
console.log(rendered);

setDataContext

Updates the data context of the template.

Syntax

template.setDataContext(data, options)

Parameters

NameTypeDescription
dataObjectNew data to set
optionsObjectAdditional options

Usage

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b>',
  data: { name: 'John' }
});


template.setDataContext({ name: 'Jane' }, { rerender: true });

clone

Creates a new Template instance from a prototype. Each clone has its own data, element, and DOM bindings; AST, CSS, and callbacks are shared with the prototype by reference.

Syntax

template.clone(settings)

Parameters

NameTypeDescription
settingsObjectPer-instance overrides like data, element, parentTemplate

Returns

Template - A new Template instance derived from this prototype.

Usage

import { Template } from '@semantic-ui/templating';


const prototype = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b>',
  isPrototype: true,
});


const instance = prototype.clone({ data: { name: 'Jane' } });

attachEvents

Attaches event handlers to the rendered template.

Syntax

template.attachEvents(events)

Parameters

NameTypeDescription
eventsObjectEvent handlers to attach

Usage

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b> <button class="greet">Greet</button>',
  data: { name: 'John' }
});


template.attachEvents({
  'click .greet': () => console.log('Greeting button clicked')
});

Lifecycle Hooks

The Template class provides several lifecycle hooks that can be overridden to add custom behavior:

  • onCreated
  • onRendered
  • onDestroyed
  • onThemeChanged

Usage

import { Template } from '@semantic-ui/templating';


const template = new Template({
  templateName: 'greet-user',
  template: 'Welcome <b>{name}</b>',
  data: { name: 'John' }
});


template.onCreated = () => console.log('Template created');
template.onRendered = () => console.log('Template rendered');
template.onDestroyed = () => console.log('Template destroyed');
template.onThemeChanged = () => console.log('Theme changed');
Previous
Abstract Syntax Tree (AST)
Next
String Scanner