Directives

Explore every Regor directive through focused live examples and syntax references.

Directives are Regor’s runtime template control surface.

By default, directive names start with r-. You can customize the prefix with RegorConfig.

BindingsControl flowComposition

Choose a directive by the behavior you need. Every topic below has a live preview with its actual source.

Core Rules

  1. r- directives are explicit full-form syntax.
  2. : is shorthand for r-bind.
  3. @ is shorthand for r-on.
  4. . shorthand binds DOM properties (equivalent to r-bind.prop).

Try it live

From form controls to stateLive Regor
FORM STATE / TWO WAYS
Name
Ada
Seats
3
Plan
Team
Email
Enabled

Controls update state. Resetting state updates the controls.

import { html, ref } from 'regor'

export function createModel(interactive = false) {
  const name = ref('Ada')
  const seats = ref(3)
  const email = ref(true)
  const plan = ref('Team')
  const reset = () => {
    name('Ada')
    seats(3)
    email(true)
    plan('Team')
  }
  return { interactive, name, seats, email, plan, reset }
}

export const modelTemplate = html` <div class="guide-demo guide-demo--split">
  <div class="guide-controls">
    <label for="model-name">Name · trim option</label
    ><input
      id="model-name"
      type="text"
      maxlength="40"
      r-model="name, { trim: true }"
      :value="name"
      :disabled="!interactive"
    />
    <label for="model-seats">Seats · .number</label
    ><input
      id="model-seats"
      type="range"
      min="1"
      max="12"
      r-model.number="seats"
      :value="seats"
      :disabled="!interactive"
    />
    <label for="model-plan">Plan</label
    ><select id="model-plan" r-model="plan" :disabled="!interactive">
      <option>Solo</option>
      <option selected>Team</option>
      <option>Studio</option>
    </select>
    <label class="guide-check"
      ><input
        type="checkbox"
        r-model="email"
        :checked="email"
        :disabled="!interactive"
      />
      Email updates</label
    ><button type="button" @click="reset" :disabled="!interactive">
      Reset from state
    </button>
  </div>
  <div class="guide-readout">
    <span class="guide-kicker">FORM STATE / TWO WAYS</span>
    <dl class="directive-values">
      <div>
        <dt>Name</dt>
        <dd>{{ name || 'Not set' }}</dd>
      </div>
      <div>
        <dt>Seats</dt>
        <dd>{{ seats }}</dd>
      </div>
      <div>
        <dt>Plan</dt>
        <dd>{{ plan }}</dd>
      </div>
      <div>
        <dt>Email</dt>
        <dd>{{ email ? 'Enabled' : 'Disabled' }}</dd>
      </div>
    </dl>
    <p>Controls update state. Resetting state updates the controls.</p>
  </div>
</div>`
import { createApp, useScope } from 'regor'
import { directiveExamples } from './examples'

const element = document.getElementById('directive-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(directiveExamples, name)) {
  const example = directiveExamples[name as keyof typeof directiveExamples]
  createApp<object>(
    useScope<object>(() => example.create(true)),
    { element, template: example.template },
  )
}

A small form brings r-model, event handling, and text bindings together. Open any directive below for a focused example.

Binding

r-text

r-text

Bind expressions to textContent and display text without interpreting it as HTML.

Explore r-text
r-html

r-html

Render trusted HTML strings and understand the boundary between text and markup.

Explore r-html
r-bind / : / .

r-bind

Bind attributes, DOM properties, and object values to reactive expressions.

Explore r-bind
r-model

r-model

Connect form controls and writable refs in both directions, with optional conversion modifiers.

Explore r-model
r-on / @

r-on

Handle DOM events with methods, expressions, and modifiers such as .prevent and .stop.

Explore r-on
r-show

r-show

Toggle visibility through display while keeping the element and its bindings mounted.

Explore r-show
:class

:class

Toggle CSS classes with object, array, or string expressions while retaining static classes.

Explore :class
:style

:style

Bind inline CSS values to state and computed style objects.

Explore :style

Control Flow

r-if / r-else-if / r-else

r-if

Mount one conditional branch at a time and remove the branch that no longer matches.

Explore r-if
r-for + :key

r-for + :key

Render reactive collections with stable keys that preserve each item’s identity.

Explore r-for + :key

Component and Utility

:is

:is

Select and mount registered components dynamically from a reactive value.

Explore :is
:context / r-context

:context

Pass multiple reactive fields into a component through object-style context input.

Explore :context
:ref

:ref

Capture element references to focus controls or integrate directly with DOM APIs.

Explore :ref
r-pre

r-pre

Leave a subtree uncompiled and preserve literal template syntax.

Explore r-pre
r-teleport

r-teleport

Move a subtree to a target selector while preserving its original binding context.

Explore r-teleport
One key identifies one item

Use stable, unique item identities when a collection can reorder, filter, or remove rows.

Important Keying Note

In r-for, both key="row.id" and :key="row.id" are expression bindings in Regor templates. Both are supported. Nested paths like a.b.c.d are supported.

Use stable keys whenever list identity matters.

Recommendation

Read in this order:

  1. r-bind
  2. r-text
  3. r-if
  4. r-for
  5. r-model