r-bind Directive

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

r-bind is Regor’s generic binding directive.

It maps to attribute binding by default, with property binding available via shorthand/flag.

r-bind / : / .Binding

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

Try it live

Attributes and properties in syncLive Regor

Live preview

Button title and accessible name Enable the button

title: Launch your next idea
disabled: false
Clicks: 0

bind.ts

import { html, ref } from 'regor'

export function createBind(interactive = false) {
  const title = ref('Launch your next idea')
  const enabled = ref(true)
  const clicks = ref(0)
  return {
    interactive,
    title,
    enabled,
    clicks,
    increment: () => clicks(clicks() + 1),
  }
}

export const bindTemplate = html` <div class="guide-demo guide-demo--split">
  <div class="guide-controls">
    <label for="bind-title">Button title and accessible name</label
    ><input
      id="bind-title"
      type="text"
      maxlength="80"
      r-model="title"
      :value="title"
      :disabled="!interactive"
    /><label class="guide-check"
      ><input type="checkbox" r-model="enabled" :disabled="!interactive" />
      Enable the button</label
    >
  </div>
  <div class="directive-card">
    <button
      class="directive-bound-button"
      type="button"
      :title="title"
      :aria-label="title"
      .disabled="!enabled || !interactive"
      @click="increment"
    >
      Try the binding
    </button>
    <dl class="directive-values">
      <div>
        <dt>title</dt>
        <dd>{{ title }}</dd>
      </div>
      <div>
        <dt>disabled</dt>
        <dd>{{ !enabled }}</dd>
      </div>
      <div>
        <dt>Clicks</dt>
        <dd>{{ clicks }}</dd>
      </div>
    </dl>
  </div>
</div>`

browser.ts

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 },
  )
}

Edit the title or disable the button. Inspect its tooltip, accessible name, and disabled property.

Syntax

<button r-bind:title="tooltip"></button>
<button :title="tooltip"></button>
<input .value="text" />
<input :value.prop="text" />

: is shorthand for r-bind: and uses attribute binding.
. shorthand uses property binding.
.prop flag switches : binding to property binding.
.camel camelizes option key before binding.

Exact runtime mapping

From RegorConfig:

r-bind:* and :* use attrDirective.
.* and :*.prop use propDirective.
:class / r-bind:class are routed to classDirective.
:style / r-bind:style are routed to styleDirective.

Supported value shapes

When an option is present (:title="x"), the first resolved value is used.

When binding without an option (r-bind="expr"), these forms are supported:

Object: { key: value, ... }
Pair array: ['key', value] (and arrays of pairs)
Flat key/value sequence: key, value, key2, value2

Example:

<div r-bind="{ id: boxId, title: hint }"></div>
<div r-bind="[dynKey, dynValue]"></div>

Dynamic key binding

For template-authored dynamic option keys, Regor uses normalized dynamic markers:

<button r-bind:_d_dynamic-key_d_="value"></button>

When dynamic attribute key changes, previous attribute is removed and new attribute is set.

Attributes and properties have different roles

Use :title for an attribute and .disabled for the DOM property. The preview shows both changing from the same context.

Notes

Attribute path handles boolean attributes and xlink:* attributes.
For DOM properties (value, checked, innerHTML, etc.), use . shorthand or .prop.
For component prop-object assignment, use :context, not r-bind="{...}".

Example

<a :href="profileUrl" :title="'Open ' + user.name">Profile</a>
<input .value="query" @input="query = $event.target.value" />
<div :class="{ active: isActive }" :style="{ color: tone }"></div>