275 lines
5.1 KiB
Markdown
275 lines
5.1 KiB
Markdown
# 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. |