# RSX in Depth

The RSX macro makes it very easy to assemble complex UIs with a very natural Rust syntax:

```rust
rsx!(
    div {
        button {
            onclick: move |e| todos.write().new_todo(),
            "Add todo"
        }
        ul {
            class: "todo-list",
            todos.iter().map(|(key, todo)| rsx!(
                li {
                    class: "beautiful-todo"
                    key: "f"
                    h3 { "{todo.title}" }
                    p { "{todo.contents}"}
                }
            ))
        }
    }
)
```

In this section, we'll cover the `rsx!` macro in depth. If you prefer to learn through examples, the `code reference` guide has plenty of examples on how to use `rsx!` effectively.

### Element structure

Attributes must come before child elements

```rust
div {
    hidden: "false",
    "some text"
    child {}
    Component {} // uppercase
    component() // lowercase is treated like a function call
    (0..10).map(|f| rsx!{ "hi {f}" }) // arbitrary rust expressions
}
```

Each element takes a comma-separated list of expressions to build the node. Roughly, here's how they work:

- `name: value` sets a property on this element.
- `"text"` adds a new text element
- `tag {}` adds a new child element
- `CustomTag {}` adds a new child component
- `{expr}` pastes the `expr` tokens literally. They must be `IntoIterator<T> where T: IntoVnode` to work properly

Commas are entirely optional, but might be useful to delineate between elements and attributes.

The `render` function provides an **extremely efficient** allocator for VNodes and text, so try not to use the `format!` macro in your components. Rust's default `ToString` methods pass through the global allocator, but all text in components is allocated inside a manually-managed Bump arena. To push you in the right direction, all text-based attributes take `std::fmt::Arguments` directly, so you'll want to reach for `format_args!` when the built-in `f-string` interpolation just doesn't cut it.

### Ignoring `cx.render` with `render!(...)`

Sometimes, writing `cx.render` is a hassle. The `rsx! macro will accept any token followed by a comma as the target to call "render" on:

```rust
cx.render(rsx!( div {} ))
// becomes
render!(div {})
```

### Conditional Rendering

Sometimes, you might not want to render an element given a condition. The rsx! macro will accept any tokens directly contained with curly braces, provided they resolve to a type that implements `IntoIterator<VNode>`. This lets us write any Rust expression that resolves to a VNode:

```rust
rsx!({
    if enabled {
        render!(div {"enabled"})
    } else {
        render!(li {"disabled"})
    }
})
```

A convenient way of hiding/showing an element is returning an `Option<VNode>`. When combined with `and_then`, we can succinctly control the display state given some boolean:

```rust
rsx!({
    a.and_then(rsx!(div {"enabled"}))
})
```

It's important to note that the expression `rsx!()` is typically lazy - this expression must be _rendered_ to produce a VNode. When using match statements, we must render every arm as to avoid the `no two closures are identical` rule that Rust imposes:

```rust
// this will not compile!
match case {
    true => rsx!(div {}),
    false => rsx!(div {})
}

// the nodes must be rendered first
match case {
    true => render!(div {}),
    false => render!(div {})
}
```

### Lists

Again, because anything that implements `IntoIterator<VNode>` is valid, we can use lists directly in our `rsx!`:

```rust
let items = vec!["a", "b", "c"];

cx.render(rsx!{
    ul {
        {items.iter().map(|f| rsx!(li { "a" }))}
    }
})
```

Sometimes, it makes sense to render VNodes into a list:

```rust
let mut items = vec![];

for _ in 0..5 {
    items.push(render!(li {} ))
}

render!({items} )
```

#### Lists and Keys

When rendering the VirtualDom to the screen, Dioxus needs to know which elements have been added and which have been removed. These changes are determined through a process called "diffing" - an old set of elements is compared to a new set of elements. If an element is removed, then it won't show up in the new elements, and Dioxus knows to remove it.

However, with lists, Dioxus does not exactly know how to determine which elements have been added or removed if the order changes or if an element is added or removed from the middle of the list.

In these cases, it is vitally important to specify a "key" alongside the element. Keys should be persistent between renders.

```rust
fn render_list(cx: Scope, items: HashMap<String, Todo>) -> DomTree {
    render!(ul {
        {items.iter().map(|key, item| {
            li {
                key: key,
                h2 { "{todo.title}" }
                p { "{todo.contents}" }
            }
        })}
    })
}
```

There have been many guides made for keys in React, so we recommend reading up to understand their importance:

- [React guide on keys](https://reactjs.org/docs/lists-and-keys.html)
- [Importance of keys (Medium)](https://kentcdodds.com/blog/understanding-reacts-key-prop)

### Complete Reference

```rust
let text = "example";

cx.render(rsx!{
    div {
        h1 { "Example" },

        {title}

        // fstring interpolation
        "{text}"

        p {
            // Attributes
            tag: "type",

            // Anything that implements display can be an attribute
            abc: 123,

            enabled: true,

            // attributes also supports interpolation
            // `class` is not a restricted keyword unlike JS and ClassName
            class: "big small wide short {text}",

            class: format_args!("attributes take fmt::Arguments. {}", 99),

            tag: {"these tokens are placed directly"}

            // Children
            a { "abcder" },

            // Children with attributes
            h2 { "hello", class: "abc-123" },

            // Child components
            CustomComponent { a: 123, b: 456, key: "1" },

            // Child components with paths
            crate::components::CustomComponent { a: 123, b: 456, key: "1" },

            // Iterators
            { (0..3).map(|i| rsx!( h1 {"{:i}"} )) },

            // More rsx!, or even html!
            { rsx! { div { } } },
            { html! { <div> </div> } },

            // Matching
            // Requires rendering the nodes first.
            // rsx! is lazy, and the underlying closures cannot have the same type
            // Rendering produces the VNode type
            {match rand::gen_range::<i32>(1..3) {
                1 => render!(h1 { "big" })
                2 => render!(h2 { "medium" })
                _ => render!(h3 { "small" })
            }}

            // Optionals
            {true.and_then(|f| rsx!( h1 {"Conditional Rendering"} ))}

            // Child nodes
            {cx.props.children}

            // Any expression that is `IntoVNode`
            {expr}
        }
    }
})
```
