Update docs to reflect changes in master (#670)

* work on updating docs to master version

* more updates

* more polishing

* finish interactivity chapter

* finish updating core guide

* fix grammer mistakes and typos

* more grammer fixes

* add liveview guide

* remove doc build

* WIP custom renderer docs

* add axum as dev-dependancy to guide

* fix examples

* fix overview example

* use md book fork to fix compilation
This commit is contained in:
ealmloff authored and GitHub committed 2023-01-06 15:00:12 -08:00
1 parent a616a8fa9d
commit cd4474cc4f
51 files changed
+870 -549

No files matched your search

+8 -8
View File
@@ -1,12 +1,12 @@
# Hooks and Component State
So far our components, being Rust functions, had no state – they were always rendering the same thing. However, in a UI component, it is often useful to have stateful functionality to build user interactions. For example, you might want to track whether the user has openend a drop-down, and render different things accordingly.
So far our components have had no state like a normal rust functions. However, in a UI component, it is often useful to have stateful functionality to build user interactions. For example, you might want to track whether the user has opened a drop-down, and render different things accordingly.
For stateful logic, you can use hooks. Hooks are Rust functions that take a reference to `ScopeState` (in a component, you can pass `&cx`), and provide you with functionality and state.
Hooks allow us to create state in our components. Hooks are Rust functions that take a reference to `ScopeState` (in a component, you can pass `cx`), and provide you with functionality and state.
## `use_state` Hook
[`use_state`](https://docs.rs/dioxus/latest/dioxus/hooks/fn.use_state.html) is one of the simplest hooks.
[`use_state`](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_state.html) is one of the simplest hooks.
- You provide a closure that determines the initial value
- `use_state` gives you the current value, and a way to update it by setting it to something else
@@ -21,7 +21,7 @@ For example, you might have seen the counter example, in which state (a number)
Every time the component's state changes, it re-renders, and the component function is called, so you can describe what you want the new UI to look like. You don't have to worry about "changing" anything – just describe what you want in terms of the state, and Dioxus will take care of the rest!
> `use_state` returns your value wrapped in a smart pointer of type [`UseState`](https://docs.rs/dioxus/latest/dioxus/hooks/struct.UseState.html). This is why you can both read the value and update it, even within a handler.
> `use_state` returns your value wrapped in a smart pointer of type [`UseState`](https://docs.rs/dioxus/latest/dioxus/prelude/struct.UseState.html). This is why you can both read the value and update it, even within an event handler.
You can use multiple hooks in the same component if you want:
@@ -40,13 +40,13 @@ But how can Dioxus differentiate between multiple hooks in the same component? A
{{#include ../../../examples/hooks_counter_two_state.rs:use_state_calls}}
```
This is only possible because the two hooks are always called in the same order, so Dioxus knows which is which. So the order you call hooks matters, which is why you must follow certain rules when using hooks:
This is only possible because the two hooks are always called in the same order, so Dioxus knows which is which. Because the order you call hooks matters, you must follow certain rules when using hooks:
1. Hooks may be only used in components or other hooks (we'll get to that later)
2. On every call to the component function
1. The same hooks must be called
2. In the same order
3. Hooks name's must start with `use_` so you don't accidentally confuse them with regular functions
3. Hooks name's should start with `use_` so you don't accidentally confuse them with regular functions
These rules mean that there are certain things you can't do with hooks:
@@ -73,11 +73,11 @@ For example, suppose we want to maintain a `Vec` of values. If we stored it with
Thankfully, there is another hook for that, `use_ref`! It is similar to `use_state`, but it lets you get a mutable reference to the contained data.
Here's a simple example that keeps a list of events in a `use_ref`. We can acquire write access to the state with `.write()`, and then just `.push` a new value to the state:
Here's a simple example that keeps a list of events in a `use_ref`. We can acquire write access to the state with `.with_mut()`, and then just `.push` a new value to the state:
```rust
{{#include ../../../examples/hooks_use_ref.rs:component}}
```
> The return values of `use_state` and `use_ref`, (`UseState` and `UseRef`, respectively) are in some ways similar to [`Cell`](https://doc.rust-lang.org/std/cell/) and [`RefCell`](https://doc.rust-lang.org/std/cell/struct.RefCell.html) – they provide interior mutability. However, these Dioxus wrappers also ensure that the component gets re-rendered whenever you change the state.
> The return values of `use_state` and `use_ref` (`UseState` and `UseRef`, respectively) are in some ways similar to [`Cell`](https://doc.rust-lang.org/std/cell/) and [`RefCell`](https://doc.rust-lang.org/std/cell/struct.RefCell.html) – they provide interior mutability. However, these Dioxus wrappers also ensure that the component gets re-rendered whenever you change the state.