r-model Directive

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

The r-model directive provides two-way data binding for form elements in your Regor components. It allows you to bind the value of form inputs to a component's data, ensuring that changes to the input are reflected in the component's data and vice versa.

r-modelForms

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

Try it live

A form and its state, connectedLive 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 },
  )
}

Change the controls, then reset from state. Both directions update the same view.

Syntax

<element r-model="expression"></element>
  • <element>: The form element (e.g., input, textarea, select) that you want to bind to.
  • expression: An expression that represents the data property you want to bind the element to. This can be a single variable or a more complex expression.

Usage

The r-model directive is commonly used with form inputs like text fields, checkboxes, radio buttons, and select elements. It establishes a two-way binding between the input's value and the specified data property in your Regor component.

Example

<div>
  <input type="text" r-model="message" />
  <p>You typed: {{ message }}</p>
</div>

In this example, the r-model directive is used to bind the value of the text input to the message property in your component's data. Any changes made to the input field will automatically update the message property, and vice versa.

Two-Way Data Binding

The r-model directive creates a two-way data binding between the form element and the component's data. This means that changes to either the form element's value or the component's data property are synchronized in real-time.

Supported Form Elements

The r-model directive can be used with various types of form elements:

  • Text Input (<input type="text">)
  • Textarea (<textarea>)
  • Select Dropdown (<select>)
  • Checkbox (<input type="checkbox">)
  • Radio Button (<input type="radio">)
  • Number Input (<input type="number"> and <input type="range">)

Example with Checkbox

<div>
  <input type="checkbox" r-model="isChecked" />
  <p>Is Checked: {{ isChecked }}</p>
</div>

In this example, the r-model directive is used with a checkbox input. The isChecked property in the component's data is bound to the checkbox's checked state. When the checkbox is toggled, the isChecked property will be updated accordingly.

Special Case: Checkbox and Select with Arrays or Sets

When the r-model directive is bound to an array or set in your component's data, it behaves differently for checkboxes and select elements:

Checkbox

If the bound expression is an array or set, the r-model directive will collect the selected values in the array or set. When multiple checkboxes are bound to the same array or set, checking or unchecking the checkboxes will add or remove values from the array or set.

<div>
  <input type="checkbox" r-model="selectedItems" value="item1" />
  <input type="checkbox" r-model="selectedItems" value="item2" />
  <input type="checkbox" r-model="selectedItems" value="item3" />
  <p>Selected Items: {{ selectedItems }}</p>
</div>

In this example, three checkboxes are bound to the selectedItems array. Checking or unchecking the checkboxes will update the selectedItems array with the selected values.

Select (Dropdown)

Similarly, when the r-model directive is bound to an array or set, and a select element with the multiple attribute is used, it will collect the selected values in the array or set.

<div>
  <select r-model="selectedOptions" multiple>
    <option value="option1">Option 1</option>
    <option value="option2">Option 2</option>
    <option value="option3">Option 3</option>
  </select>
  <p>Selected Options: {{ selectedOptions }}</p>
</div>

In this example, the r-model directive is used with a multi-select dropdown. The selectedOptions array will contain the selected values from the dropdown.

Modifiers

The live preview passes the trim option explicitly as a second expression: r-model="name, { trim: true }". This is equivalent to r-model.trim="name" and trims the value written to the ref as you type.

The r-model directive supports modifiers to enable additional behavior on the bound element. Modifiers are added to the directive with a dot notation.

Example with Modifiers

<div>
  <input type="text" r-model.trim="trimmedMessage" />
  <p>Trimmed Message: {{ trimmedMessage }}</p>
</div>

The .trim modifier trims the bound state as you type and trims the text control when it emits change.

Available Modifiers

  • .trim: Removes leading and trailing whitespace from the bound text value during input and from the text control on change.
  • .lazy: Updates the component's data property on change instead of input. The event type is chosen when the control is mounted.
  • .number: Converts input and textarea values with parseFloat. Number and range inputs apply this conversion automatically. On selects, numeric option values are converted while nonnumeric values are preserved.
  • .int: Converts input and textarea values with parseInt, truncating fractional digits. It takes precedence over .number, including on number and range inputs.

You can use these modifiers individually or combine them to achieve the desired behavior for your form elements.

Modifiers can also be supplied as a second expression, using a string or an options object:

<input r-model="amount, 'number'" />
<input r-model="count, { int: true }" />
<input r-model.lazy="count, { int: true }" />

Dot modifiers and expression options are combined. A false expression option does not disable a dot modifier. Conversion and trim options are read on each event, so reactive expression options can be enabled or disabled after mounting. Options objects can contain refs, including the fields created by ref({ number: false }). Changes take effect on the next input or change event; changing an option does not convert the existing model value.

With numeric conversion enabled on inputs and textareas, empty values and values that cannot be parsed become ''. Conversion follows JavaScript's parsing rules: 7.8 becomes 7 with .int, and 12px becomes 12 with either numeric modifier.

Bind to writable state

Computed values are read-only. Bind r-model to a writable ref, then derive summaries from that state.

Notes

  • The r-model directive is ideal for creating interactive forms and ensuring that user input is synchronized with your component's data.

  • For checkboxes and radio buttons, the r-model directive binds the checked property of the element to the data property, reflecting the boolean state of the checkbox or radio button.

  • Changes to the input element's value due to user interactions, such as typing in a text field or selecting options in a dropdown, are automatically reflected in the bound data property.

  • Changes to the data property bound with r-model are automatically reflected in the form element's value, allowing you to programmatically update the input's content.

  • Modifiers provide additional control over the data binding behavior, allowing you to customize how data is processed and updated between the form element and the component's data.

The r-model directive simplifies the process of creating interactive forms in your Regor-powered applications by enabling two-way data binding between form elements and your component's data properties. It ensures that your forms remain in sync with the underlying data, providing a seamless user experience.

Back to the directives

Keep exploring Handle form events.