Templates and Directives

Udodi templates are HTML-first and use a small declarative DSL for connecting markup to component state, events, and DOM behavior.

Templates remain close to standard HTML while Udodi directives provide reactive bindings, event handling, conditional rendering, list rendering, DOM references, attribute and style updates, and other UI behavior.

Form-specific directives such as @form, @validate, and @submit are documented separately under Forms.

Guides

Start here → Template Overview

Templates in a Component

A component's template defines the DOM structure rendered by the component.

import { createComponent, html, render } from "udodi";

const Hello = createComponent({
  name: "Hello",

  state() {
    return {
      userName: "Celestine",
    };
  },

  template: () => html`
    <p>
      Hello, <span @text="userName"></span>
    </p>
  `,
});

render(Hello(), "#app");

Templates can access values exposed through the component's public context, including state, computed values, methods, and props.

See Context for the complete context model.

Directive Map

Directive	Role
`@text`	Reactive text content
`@bind`	Two-way binding for form controls
`@on`	Event listeners
`@ref`	Named DOM element references
`@if` / `@elseif` / `@else`	Conditional DOM presence
`@show`	Conditional visibility (`hidden`)
`@for`	List rendering
`@class`	Static and reactive class lists
`@style`	Static and reactive inline styles
`@attr`	Reactive attributes
`@teleport`	Render content into another DOM target

Template Model

text

  template
     │
     ▼
  lexer / parser
     │
     ▼
  compiler
     │
     ▼
  instructions
     │
     ▼
    VM
     │
     ▼
  live DOM

The compiler and VM are internal implementation details. Application code normally interacts with the template DSL rather than these runtime layers.

Reactive directives establish dependencies on the values they read, allowing Udodi to update the affected DOM when those values change.

See Reactivity for the underlying reactive system.

Design Notes

HTML-first — templates look like HTML with a small set of @ attributes.
Fine-grained updates — bindings subscribe to the values they read, not whole components.
Explicit directives — text, classes, styles, attributes, and events each have a dedicated directive.
One root element — a component template must produce exactly one root element at mount time.
Forms elsewhere — validation and submit flows live under Forms, not in this section.

When to Use Which Guide

Goal	Guide
Big picture and mental model	Template Overview
Expression syntax and DSL rules	Template DSL
Display reactive text	`@text`
Two-way inputs	`@bind`
Clicks and other events	`@on`
Hold a DOM node on the component	`@ref`
Mount / unmount by condition	`@if`
Toggle visibility without destroying DOM	`@show`
Render lists	`@for`
Toggle classes from state	`@class`
Set inline styles from state	`@style`
Bind arbitrary attributes	`@attr`
Render into another part of the document	`@teleport`

Next Steps

Template Overview — start here
Template DSL — expression and directive syntax
Reactivity Overview — how bindings stay in sync
Components — where template lives on a component
Forms — @form, @validate, @submit

Templates and Directives ​

Guides ​

Templates in a Component ​

Directive Map ​

Template Model ​

Design Notes ​

When to Use Which Guide ​

Next Steps ​