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

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.

SUI is designed to be flexible in terms of how components are rendered, currently Semantic ships with the Lit rendering engine which will compile templates to lit html for use with web components.

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
stateConfigObjectConfiguration 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: ‘lit’)
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
onUpdatedFunctionCallback when the template is updated
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 { Template, TemplateCompiler } 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()
  },
  stateConfig: {
    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

TemplateResult - The rendered template content (typically a Lit TemplateResult).

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 copy of the template with optional new settings.

Syntax

template.clone(settings)

Parameters

NameTypeDescription
settingsObjectNew settings to apply to the clone

Returns

Template - A new Template instance.

Usage

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


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


const clonedTemplate = template.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');