AlpineJS Skill: Two-Way Data Binding (`x-model`)

x-model can be applied to various form elements:

• Text Inputs:

  Binds the value of a text input, textarea, or password input to a data property.

  <input type="text" x-model="message">
  <p>You typed: <span x-text="message"></span></p>

• Checkboxes:

  • Single Checkbox (Boolean): Binds the checked state to a boolean data property. If the checkbox has a value attribute, x-model will populate an array with the values of the checked checkboxes. If no value attribute is present, it will be a boolean.

    <input type="checkbox" id="agree" x-model="isAgreed">
    <label for="agree">I agree to the terms.</label>
    <p>Agreed: <span x-text="isAgreed"></span></p>

  • Multiple Checkboxes (Array): When multiple checkboxes share the same x-model property and have value attributes, AlpineJS will manage an array of the checked values.

    <!-- In x-data: selectedColors: [] -->
    <input type="checkbox" value="red" x-model="selectedColors"> Red
    <input type="checkbox" value="green" x-model="selectedColors"> Green
    <p>Selected: <span x-text="selectedColors.join(', ')"></span></p>

• Radio Buttons:

  Binds the value of the selected radio button in a group to a data property.

  <!-- In x-data: favoriteColor: '' -->
  <input type="radio" value="blue" x-model="favoriteColor"> Blue
  <input type="radio" value="yellow" x-model="favoriteColor"> Yellow
  <p>Favorite: <span x-text="favoriteColor"></span></p>

• Select Dropdowns:

  Binds the value of the selected option to a data property. For <select multiple>, it binds to an array of selected option values.

  <!-- In x-data: chosenOption: '' -->
  <select x-model="chosenOption">
    <option value="">--Please choose an option--</option>
    <option value="A">Option A</option>
    <option value="B">Option B</option>
  </select>
  <p>Chosen: <span x-text="chosenOption"></span></p>

Modifiers for x-model:

• .lazy: By default, x-model updates the data property on every input event. With .lazy, it only updates on the change event (e.g., when the input loses focus).

  <input type="text" x-model.lazy="username">

• .number: Automatically typecasts the input's value to a JavaScript number. If the value cannot be converted to a number, it remains unchanged.

  <input type="text" x-model.number="age">

  Note: For <input type="number">, this is particularly useful as values can still be strings without .number.

• .debounce: Delays the update of the data property until a certain amount of time has passed without any new input. This is useful for performance-intensive updates, like live search queries.

  <!-- Waits 500ms after last keystroke -->
  <input type="text" x-model.debounce.500ms="searchTerm">
  
  <!-- Default debounce is 250ms -->
  <input type="text" x-model.debounce="searchTerm">

• .trim: Automatically trims leading/trailing whitespace from the input value.

  <input type="text" x-model.trim="comment">

• Initial value of the input not matching x-model data:

  If an input element has an HTML value attribute (e.g., <input type="text" value="Initial HTML Value" x-model="myProp">) and x-model is also set, AlpineJS's data property defined in x-data will take precedence for the initial state. For example, if x-data="{ myProp: 'Alpine Value' }", the input will display "Alpine Value". It's best practice to define the initial state of your data solely within the x-data object and let x-model reflect that, rather than relying on HTML value attributes for initial Alpine state. This keeps your state management clear and centralized in JavaScript.

• Using x-model on non-form elements:

  x-model is specifically designed for form elements like <input>, <select>, and <textarea>. Attempting to use x-model on elements like <div> or <p> will not work for two-way data binding as these elements don't have an intrinsic "value" that a user can change. For displaying data in such elements (one-way binding), use directives like x-text, x-html, or attribute binding with x-bind:attributeName.

• Not typecasting with .number for numerical inputs:

  Values retrieved from text inputs (even <input type="number">) are typically strings by default. If you bind x-model to such an input and expect the corresponding data property to be a JavaScript Number type, you might be surprised to find it's a string. To automatically cast the input value to a number, always use the .number modifier: x-model.number="myNumericProperty". Without it, a value like "123" will be stored as the string "123", not the number 123, which can lead to unexpected behavior in calculations or comparisons (e.g., "10" + 5 results in "105", not 15).