181 lines
3.0 KiB
Markdown
181 lines
3.0 KiB
Markdown
# Alpine.js Documentation - Directives
|
|
|
|
Alpine directives are attributes that you can add to HTML elements to give them special behavior.
|
|
|
|
## [x-for](/directives/for)
|
|
|
|
Alpine's `x-for` directive allows you to create DOM elements by iterating through a list. Here's a simple example of using it to create a list of colors based on an array.
|
|
|
|
```
|
|
<ul x-data="{ colors: ['Red', 'Orange', 'Yellow'] }">
|
|
|
|
|
|
n<template x-for="color in colors">
|
|
|
|
|
|
n<li x-text="color"></li>
|
|
|
|
|
|
n</template>
|
|
|
|
|
|
n</ul>
|
|
```
|
|
|
|
You may also pass objects to `x-for`.
|
|
|
|
```
|
|
<ul x-data="{ car: { make: 'Jeep', model: 'Grand Cherokee', color: 'Black' } }">
|
|
|
|
|
|
n<template x-for="(value, index) in car">
|
|
|
|
|
|
n<li>
|
|
|
|
|
|
n<span x-text="index"></span>: <span x-text="value"></span>
|
|
|
|
|
|
n</li>
|
|
|
|
|
|
n</template>
|
|
|
|
|
|
n</ul>
|
|
```
|
|
|
|
There are two rules worth noting about `x-for`:
|
|
|
|
> `x-for` MUST be declared on a `<template>` element.
|
|
> That `<template>` element MUST contain only one root element
|
|
|
|
### [Keys](#keys)
|
|
|
|
It is important to specify unique keys for each `x-for` iteration if you are going to be re-ordering items. Without dynamic keys, Alpine may have a hard time keeping track of what re-orders and will cause odd side-effects.
|
|
|
|
```
|
|
<ul x-data="{ colors: [
|
|
|
|
|
|
n{ id: 1, label: 'Red' },
|
|
|
|
|
|
n{ id: 2, label: 'Orange' },
|
|
|
|
|
|
n{ id: 3, label: 'Yellow' },
|
|
|
|
|
|
n]}">
|
|
|
|
|
|
n<template x-for="color in colors" :key="color.id">
|
|
|
|
|
|
n<li x-text="color.label"></li>
|
|
|
|
|
|
n</template>
|
|
|
|
|
|
n</ul>
|
|
```
|
|
|
|
Now if the colors are added, removed, re-ordered, or their "id"s change, Alpine will preserve or destroy the iterated `<li>`elements accordingly.
|
|
|
|
### [Accessing indexes](#accessing-indexes)
|
|
|
|
If you need to access the index of each item in the iteration, you can do so using the `([item], [index]) in [items]` syntax like so:
|
|
|
|
```
|
|
<ul x-data="{ colors: ['Red', 'Orange', 'Yellow'] }">
|
|
|
|
|
|
n<template x-for="(color, index) in colors">
|
|
|
|
|
|
n<li>
|
|
|
|
|
|
n<span x-text="index + ': '"></span>
|
|
|
|
|
|
n<span x-text="color"></span>
|
|
|
|
|
|
n</li>
|
|
|
|
|
|
n</template>
|
|
|
|
|
|
n</ul>
|
|
```
|
|
|
|
You can also access the index inside a dynamic `:key` expression.
|
|
|
|
```
|
|
<template x-for="(color, index) in colors" :key="index">
|
|
```
|
|
|
|
### [Iterating over a range](#iterating-over-a-range)
|
|
|
|
If you need to simply loop `n` number of times, rather than iterate through an array, Alpine offers a short syntax.
|
|
|
|
```
|
|
<ul>
|
|
|
|
|
|
n<template x-for="i in 10">
|
|
|
|
|
|
n<li x-text="i"></li>
|
|
|
|
|
|
n</template>
|
|
|
|
|
|
n</ul>
|
|
```
|
|
|
|
`i` in this case can be named anything you like.
|
|
|
|
> Despite not being included in the above snippet, `x-for` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
|
|
|
|
### [Contents of a `<template>`](#contents-of-a-template)
|
|
|
|
As mentioned above, an `<template>` tag must contain only one root element.
|
|
|
|
For example, the following code will not work:
|
|
|
|
```
|
|
<template x-for="color in colors">
|
|
|
|
|
|
n<span>The next color is </span><span x-text="color">
|
|
|
|
|
|
n</template>
|
|
```
|
|
|
|
but this code will work:
|
|
|
|
```
|
|
<template x-for="color in colors">
|
|
|
|
|
|
n<p>
|
|
|
|
|
|
n<span>The next color is </span><span x-text="color">
|
|
|
|
|
|
n</p>
|
|
|
|
|
|
n</template>
|
|
```
|
|
|
|
Code highlighting provided by [Torchlight](https://torchlight.dev/) |