offline docs

offline-docs/alpinejs/directives/model.md

@@ -0,0 +1,275 @@
+# Alpine.js Documentation - Directives
+
+Alpine directives are attributes that you can add to HTML elements to give them special behavior.
+
+## [x-model](/directives/model)
+
+`x-model` allows you to bind the value of an input element to Alpine data.
+
+Here's a simple example of using `x-model` to bind the value of a text field to a piece of data in Alpine.
+
+```
+<div x-data="{ message: '' }">
+
+
+n<input type="text" x-model="message">
+
+
+n<span x-text="message"></span>
+
+
+n</div>
+```
+
+Now as the user types into the text field, the `message` will be reflected in the `<span>` tag.
+
+`x-model` is two-way bound, meaning it both "sets" and "gets". In addition to changing data, if the data itself changes, the element will reflect the change.
+
+We can use the same example as above but this time, we'll add a button to change the value of the `message` property.
+
+```
+<div x-data="{ message: '' }">
+
+
+n<input type="text" x-model="message">
+
+
+n<button x-on:click="message = 'changed'">Change Message</button>
+
+
+n</div>
+```
+
+Now when the `<button>` is clicked, the input element's value will instantly be updated to "changed".
+
+`x-model` works with the following input elements:
+
+* `<input type="text">`
+* `<textarea>`
+* `<input type="checkbox">`
+* `<input type="radio">`
+* `<select>`
+* `<input type="range">`
+
+### [Text inputs](#text-inputs)
+
+```
+<input type="text" x-model="message">
+
+
+n<span x-text="message"></span>
+```
+
+> Despite not being included in the above snippet, `x-model` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
+
+### [Textarea inputs](#textarea-inputs)
+
+```
+<textarea x-model="message"></textarea>
+
+
+n<span x-text="message"></span>
+```
+
+### [Checkbox inputs](#checkbox-inputs)
+
+#### [Single checkbox with boolean](#single-checkbox-with-boolean)
+
+```
+<input type="checkbox" id="checkbox" x-model="show">
+
+
+n<label for="checkbox" x-text="show"></label>
+```
+
+#### [Multiple checkboxes bound to array](#multiple-checkboxes-bound-to-array)
+
+```
+<input type="checkbox" value="red" x-model="colors">
+
+
+n<input type="checkbox" value="orange" x-model="colors">
+
+
+n<input type="checkbox" value="yellow" x-model="colors">
+
+
+nColors: <span x-text="colors"></span>
+```
+
+Colors:
+
+### [Radio inputs](#radio-inputs)
+
+```
+<input type="radio" value="yes" x-model="answer">
+
+
+n<input type="radio" value="no" x-model="answer">
+
+
+nAnswer: <span x-text="answer"></span>
+```
+
+Answer:
+
+### [Select inputs](#select-inputs)
+
+#### [Single select](#single-select)
+
+```
+<select x-model="color">
+
+
+n<option>Red</option>
+
+
+n<option>Orange</option>
+
+
+n<option>Yellow</option>
+
+
+n</select>
+
+
+nColor: <span x-text="color"></span>
+```
+
+Color:
+
+#### [Single select with placeholder](#single-select-with-placeholder)
+
+```
+<select x-model="color">
+
+
+n<option value="" disabled>Select A Color</option>
+
+
+n<option>Red</option>
+
+
+n<option>Orange</option>
+
+
+n<option>Yellow</option>
+
+
+n</select>
+
+
+nColor: <span x-text="color"></span>
+```
+
+Color:
+
+#### [Multiple select](#multiple-select)
+
+```
+<select x-model="color" multiple>
+
+
+n<option>Red</option>
+
+
+n<option>Orange</option>
+
+
+n<option>Yellow</option>
+
+
+n</select>
+
+
+nColors: <span x-text="color"></span>
+```
+
+Color:
+
+#### [Dynamically populated Select Options](#dynamically-populated-select-options)
+
+```
+<select x-model="color">
+
+
+n<template x-for="color in ['Red', 'Orange', 'Yellow']">
+
+
+n<option x-text="color"></option>
+
+
+n</template>
+
+
+n</select>
+
+
+nColor: <span x-text="color"></span>
+```
+
+Color:
+
+### [Range inputs](#range-inputs)
+
+```
+<input type="range" x-model="range" min="0" max="1" step="0.1">
+
+
+n<span x-text="range"></span>
+```
+
+### [Modifiers](#modifiers)
+
+#### [`.lazy`](#lazy)
+
+On text inputs, by default, `x-model` updates the property on every keystroke. By adding the `.lazy` modifier, you can force an `x-model` input to only update the property when user focuses away from the input element.
+
+This is handy for things like real-time form-validation where you might not want to show an input validation error until the user "tabs" away from a field.
+
+```
+<input type="text" x-model.lazy="username">
+
+
+n<span x-show="username.length > 20">The username is too long.</span>
+```
+
+#### [`.number`](#number)
+
+By default, any data stored in a property via `x-model` is stored as a string. To force Alpine to store the value as a JavaScript number, add the `.number` modifier.
+
+```
+<input type="text" x-model.number="age">
+
+
+n<span x-text="typeof age"></span>
+```
+
+#### [`.boolean`](#boolean)
+
+By default, any data stored in a property via `x-model` is stored as a string. To force Alpine to store the value as a JavaScript boolean, add the `.boolean` modifier. Both integers (1/0) and strings (true/false) are valid boolean values.
+
+```
+<select x-model.boolean="isActive">
+
+
+n<option value="true">Yes</option>
+
+
+n<option value="false">No</option>
+
+
+n</select>
+
+
+n<span x-text="typeof isActive"></span>
+```
+
+#### [`.debounce`](#debounce)
+
+By adding `.debounce` to `x-model`, you can easily debounce the updating of bound input.
+
+This is useful for things like real-time search inputs that fetch new data from the server every time the search property changes.
+
+```
+<input type="text" x-model.