---
title: 'Lists'
---

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

## Iterators

Yew supports two different syntaxes for building HTML from an iterator.

<Tabs>
  <TabItem value="Syntax type 1" label="Syntax type 1">

The first is to call `collect::<Html>()` on the final transform in your iterator, which returns a
list that Yew can display.

```rust
use yew::prelude::*;

let items = (1..=10).collect::<Vec<_>>();

html! {
    <ul class="item-list">
        { items.iter().collect::<Html>() }
    </ul>
};
```

  </TabItem>
  <TabItem value="Syntax type 2" label="Syntax type 2">

The alternative is to use the `for` keyword, which is not native Rust syntax and instead is used by
the HTML macro to output the needed code to display the iterator.

```rust
use yew::prelude::*;

let items = (1..=10).collect::<Vec<_>>();

html! {
    <ul class="item-list">
        { for items.iter() }
    </ul>
};
```

  </TabItem>
</Tabs>

## Keyed lists

A keyed list is an optimized list that has keys on **all** children.
`key` is a special prop provided by Yew which gives an html element or component a unique identifier
which is used for optimization purposes inside Yew.

:::caution
Key has to be unique only in each list, in constrast to the global uniqueness of html `id`s. It must not depend on the order of the list.
:::

It is always recommended to add keys to lists.

Keys can be added by passing a unique `String`, `str` or integer to the special `key` prop:

```rust , ignore
use yew::prelude::*;

let names = vec!["Sam","Bob","Ray"]

html! {
    <div id="introductions">
        {
            names.into_iter().map(|name| {
                html!{<div key={name}>{ format!("Hello, I'am {}!",name) }</div>}
            }).collect::<Html>()
        }
    </div>
};

```

### Performance increases

We have [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list) example that lets you test the performance improvements, but here is rough rundown:

1. Go to [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list) hosted demo
2. Add 500 elements.
3. Disable keys.
4. Reverse the list.
5. Look at "The last rendering took Xms" (At the time of writing this it was ~60ms)
6. Enable keys.
7. Reverse the list.
8. Look at "The last rendering took Xms" (At the time of writing this it was ~30ms)

So just at the time of writing this, for 500 components its a x2 increase of speed.

### Detailed explanation

Usually you just need a key on every list item when you iterate and the order of data can change.
It's used to speed up the reconciliation process when re-rendering the list.

Without keys, lets assume you iterate through `["bob","sam","rob"]`, ending up with the html:

```html
<div id="bob">My name is Bob</div>
<div id="sam">My name is Sam</div>
<div id="rob">My name is rob</div>
```

Then on the next render, if your list changed to `["bob","rob"]`, yew could delete
the element with id="rob" and update id="sam" to be id="rob"

If you had added a key to each element, the initial html would be the same, but after
the render with the modified list, `["bob","rob"]`, yew would just delete the second
html element and leave the rest untouched since it can use the keys to associate them.

If you ever encounter a bug/"feature" where you switch from one component to another but both have a div as the highest rendered element.
Yew reuses the rendered html div in those cases as an optimization.
If you need that div to be recreated instead of reused, then you can add different keys and they wont be reused

## Further reading

-   [TodoMVC](https://github.com/yewstack/yew/tree/master/examples/todomvc)
-   [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list)
-   [Router](https://github.com/yewstack/yew/tree/master/examples/router)
