};
+```
+
+`html!` macro allows you to write html generation as if it was in a `.html` file and then behind the scenes by yew gets turned into internal builder patterns that generate all DOM nodes.
+
+As it is part of rust code it provides a easy way to switch from html to rust by applying curly brackets:
+
+```rust
+use yew::prelude::*;
+
+let header_text = "Hello world".to_string();
+let header_html: Html = html!{{header_text}
}; + +let count: usize = 5; +let counter_html: Html = html!{{"My age is: "}{count}
}; + +let combined_html: Html = html!{{header_html}{counter_html}
};
+```
+
+One rule major rule comes with use of `html!` - you can only return 1 wrapping node:
+
+
+
+
+
+};
+
+```
+
+
-
- { "App title" }
-
-
- { "Somewhere" }
-
-
- }
+#[function_component]
+fn Navbar(props: &NavbarProps) -> Html {
+ html! {
+
+
+ { "App title" }
+
+
+ { "Somewhere" }
+
+
}
}
@@ -51,14 +42,14 @@ pub struct ThemeProps {
children: Children,
}
-#[yew::function_component(Title)]
-fn title(_props: &ThemeProps) -> Html {
+#[function_component]
+fn Title(_props: &ThemeProps) -> Html {
html! {
// impl
}
}
-#[yew::function_component(NavButton)]
-fn nav_button(_props: &ThemeProps) -> Html {
+#[function_component]
+fn NavButton(_props: &ThemeProps) -> Html {
html! {
// impl
}
@@ -75,16 +66,17 @@ html! {
};
```
-Passing down data like this isn't ideal for something like a theme which needs to be available everywhere.
+Passing down data like this isn't ideal for something like a theme which needs to be available everywhere.
This is where contexts come in.
-Contexts provide a way to share data between components without passing them down explicitly as props.
-They make data available to all components in the tree.
+Contexts can be understood as a global-ish opt in props.
+You need to provide the value somewhere in the component tree and all sub-components will be able to listen into its value and changes.
## Using Contexts
In order to use contexts, we need a struct which defines what data is to be passed.
For the above use-case, consider the following struct:
+
```rust
#[derive(Clone, Debug, PartialEq)]
struct Theme {
@@ -101,49 +93,9 @@ The children are re-rendered when the context changes.
#### Struct components
-The `Scope::context` method is used to consume contexts in struct components.
-
-##### Example
-
-```rust
-use yew::{Callback, html, Component, Context, Html};
-
-#[derive(Clone, Debug, PartialEq)]
-struct Theme {
- foreground: String,
- background: String,
-}
-
-struct ContextDemo;
-
-impl Component for ContextDemo {
- type Message = ();
- type Properties = ();
-
- fn create(_ctx: &Context- { "Rendered at: " } - { &props.time } -
- } -} -``` - -
-
-
- }
-}
-```
-
- - { "Current value: " } - { *counter } -
-- { &props.data } -
- } -} - -// used like this -html! { -{"THE SKY"}
+
+ // highlight-next-line
+ { for props.children.iter() } //then use like this
+
+ }
+}
+
+```
+
+## Further reading
+
+- [Advanced ways to handle children](../../advanced-topics/children)
diff --git a/website/docs/concepts/function-components/communication.mdx b/website/docs/concepts/function-components/communication.mdx
new file mode 100644
index 00000000000..250543666b2
--- /dev/null
+++ b/website/docs/concepts/function-components/communication.mdx
@@ -0,0 +1,11 @@
+---
+title: "Communication between components"
+---
+
+## Parent to child messaging
+
+Pass data as [props](./properties) that cause a rerender, this is the way to pass messages to children.
+
+## Child to parent messaging
+
+Pass down a callback via props, that the child on an event can call. [Example](callbacks#passing-callbacks-as-props)
diff --git a/website/docs/concepts/function-components/generics.mdx b/website/docs/concepts/function-components/generics.mdx
new file mode 100644
index 00000000000..6a5ac49f3cf
--- /dev/null
+++ b/website/docs/concepts/function-components/generics.mdx
@@ -0,0 +1,44 @@
+---
+title: "Generic Components"
+description: "The #[function_component] attribute"
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+The `#[function_component]` attribute also works with generic functions for creating generic components.
+
+```rust
+use std::fmt::Display;
+use yew::{function_component, html, Properties, Html};
+
+#[derive(Properties, PartialEq)]
+pub struct Props+ { &props.data } +
+ } +} + +// then can be used like this +html! { +
+
+ }
+}
+
+/// Button placed in `Toolbar`.
+/// As this component is a child of `ThemeContextProvider` in the component tree, it also has access to the context.
+#[function_component]
+pub fn ThemedButton() -> Html {
+ //highlight-next-line
+ let theme = use_context::
+ { (*message).clone() }
+
+ }
+}
+```
diff --git a/website/docs/concepts/function-components/hooks/use-mut-ref.mdx b/website/docs/concepts/function-components/hooks/use-mut-ref.mdx
new file mode 100644
index 00000000000..8fd148d8597
--- /dev/null
+++ b/website/docs/concepts/function-components/hooks/use-mut-ref.mdx
@@ -0,0 +1,55 @@
+---
+title: "use_mut_ref"
+---
+
+`use_mut_ref` is used for obtaining a mutable reference to a value.
+Its state persists across renders.
+
+It is important to note that you do not get notified of state changes.
+If you need the component to be re-rendered on state change, consider using [`use_state`](./use-state).
+
+## Example
+
+Here you can see we count `message_count` as that number is not used in `Html` and thus does not need to cause a rerender.
+
+```rust
+use web_sys::HtmlInputElement;
+use yew::{
+ events::Event,
+ function_component, html, use_mut_ref, use_state,
+ Callback, TargetCast,
+ Html,
+};
+
+#[function_component]
+fn MutRefExample() -> Html {
+ let message = use_state(|| "".to_string());
+ let message_count = use_mut_ref(|| 0);
+
+ let onclick = Callback::from(move |_| {
+ let window = gloo::utils::window();
+
+ if *message_count.borrow_mut() > 3 {
+ window.alert_with_message("Message limit reached").unwrap();
+ } else {
+ *message_count.borrow_mut() += 1;
+ window.alert_with_message("Message sent").unwrap();
+ }
+ });
+
+ let onchange = {
+ let message = message.clone();
+ Callback::from(move |e: Event| {
+ let input: HtmlInputElement = e.target_unchecked_into();
+ message.set(input.value());
+ })
+ };
+
+ html! {
+
+
+
+
+ }
+}
+```
diff --git a/website/docs/concepts/function-components/hooks/use-node-ref.mdx b/website/docs/concepts/function-components/hooks/use-node-ref.mdx
new file mode 100644
index 00000000000..ac04638d1fe
--- /dev/null
+++ b/website/docs/concepts/function-components/hooks/use-node-ref.mdx
@@ -0,0 +1,50 @@
+---
+title: "use_node_ref"
+---
+
+`use_node_ref` is used for maintaining an easy reference to the DOM element represented as a `NodeRef`. It also persists across renders.
+
+## Example
+
+```rust
+use web_sys::HtmlInputElement;
+use yew::{
+ function_component, functional::*, html,
+ NodeRef, Html
+};
+
+#[function_component(UseRef)]
+pub fn ref_hook() -> Html {
+ // highlight-next-line
+ let input_ref = use_node_ref();
+ let value = use_state(|| 25_f64);
+
+ let onclick = {
+ let input_ref = input_ref.clone();
+ let value = value.clone();
+ move |_| {
+ // highlight-start
+ if let Some(input) = input_ref.cast::
+ // highlight-next-line
+
+
+
+ }
+}
+```
+
+:::tip Advanced tip
+
+When conditionally rendering elements you can use `NodeRef` in conjunction with `use_effect_with_deps`
+to perform actions each time an element is rendered and just before its going to be removed from the
+DOM.
+
+:::
diff --git a/website/docs/concepts/function-components/hooks/use-reducer.mdx b/website/docs/concepts/function-components/hooks/use-reducer.mdx
new file mode 100644
index 00000000000..d8f1d027755
--- /dev/null
+++ b/website/docs/concepts/function-components/hooks/use-reducer.mdx
@@ -0,0 +1,109 @@
+---
+title: "use_reducer"
+---
+
+`use_reducer` is an alternative to [`use_state`](./use-state). It is used to handle more complex component's state.
+
+It accepts an initial state function and returns a `UseReducerHandle` that dereferences to the state,
+and a dispatch function.
+The dispatch function takes one argument of type `Action`. When called, the action and current value
+are passed to the reducer function which computes a new state that is returned,
+and the component is re-rendered.
+
+:::tip Advanced tip
+
+The dispatch function is guaranteed to be the same across the entire
+component lifecycle. You can safely omit the `UseReducerHandle` from the
+dependents of `use_effect_with_deps` if you only intend to dispatch
+values from within the hooks.
+
+:::
+
+The state object returned by the initial state function is required to
+implement a `Reducible` trait which provides an `Action` type and a
+reducer function.
+
+This hook will always trigger a re-render upon receiving an action. See
+[`use_reducer_eq`](#use_reducer_eq) if you want the component to only
+re-render when the state changes.
+
+## Example
+
+```rust
+use yew::prelude::*;
+use std::rc::Rc;
+
+/// reducer's Action
+enum CounterAction {
+ Double,
+ Square,
+}
+
+/// reducer's State
+struct CounterState {
+ counter: i32,
+}
+
+impl Default for CounterState {
+ fn default() -> Self {
+ Self { counter: 1 }
+ }
+}
+
+impl Reducible for CounterState {
+ /// Reducer Action Type
+ type Action = CounterAction;
+
+ /// Reducer Function
+ fn reduce(self: Rc{ counter.counter }
+
+
+
+
+ }
+}
+```
+
+:::caution
+
+The value held in the handle will reflect the value of at the time the
+handle is returned by the `use_reducer`. It is possible that the handle does
+not dereference to an up to date value if you are moving it into a
+`use_effect_with_deps` hook. You can register the
+state to the dependents so the hook can be updated when the value changes.
+
+:::
+
+## `use_reducer_eq`
+
+This hook has the same effect as `use_reducer` but will only trigger a
+re-render when the reducer function produces a value that `prev_state != next_state`.
+
+This hook requires the state object to implement `PartialEq` in addition
+to the `Reducible` trait required by `use_reducer`.
diff --git a/website/docs/concepts/function-components/hooks/use-state.mdx b/website/docs/concepts/function-components/hooks/use-state.mdx
new file mode 100644
index 00000000000..1bf1a64ce22
--- /dev/null
+++ b/website/docs/concepts/function-components/hooks/use-state.mdx
@@ -0,0 +1,67 @@
+---
+title: "use_state"
+---
+
+`use_state` is used to manage state in a function component.
+It returns a `UseStateHandle` object which `Deref`s to the currently stored value
+and provides a `set` method to update the value.
+
+The hook takes a function as input which determines the initial value.
+
+:::tip Advanced tip
+
+The setter function is guaranteed to be the same across the entire
+component lifecycle. You can safely omit the `UseStateHandle` from the
+dependents of `use_effect_with_deps` if you only intend to set
+values from within the hook.
+
+:::
+
+This hook will always trigger a re-render upon receiving a new state. See
+[`use_state_eq`](#use_state_eq) if you want the component to only
+re-render when the state changes.
+
+## Example
+
+```rust
+use std::ops::Deref;
+use yew::{Callback, function_component, html, use_state, Html};
+
+#[function_component]
+fn StateExample() -> Html {
+ let name_handle = use_state(|| String::from("Bob"));
+ let name = name_handle.deref().clone();
+ let onclick = {
+ let name = name.clone();
+ Callback::from(move |_| name_handle.set(format!("{}y Jr.", name)))
+ };
+
+
+ html! {
+
+
+
+ }
+}
+```
+
+:::caution
+
+The value held in the handle will reflect the value at the time the
+handle is returned by the `use_state`. It is possible that the handle
+does not dereference to an up to date value if you are moving it into a
+`use_effect_with_deps` hook. You can register the
+state to the dependents so the hook can be updated when the value changes.
+
+:::
+
+## `use_state_eq`
+
+This hook has the same effect as `use_state` but will only trigger a
+re-render when the setter receives a value that `prev_state != next_state`.
+
+This hook requires the state object to implement `PartialEq`.
diff --git a/website/docs/concepts/function-components/introduction.mdx b/website/docs/concepts/function-components/introduction.mdx
index 64098c07238..1f6a8f6fa1d 100644
--- a/website/docs/concepts/function-components/introduction.mdx
+++ b/website/docs/concepts/function-components/introduction.mdx
@@ -1,19 +1,35 @@
---
title: "Function Components"
-sidebar_label: Introduction
-description: "Introduction to function components "
+slug: /concepts/function-components
---
-Function components are a simplified version of normal components. They consist of a single function
-that receives props and determines what should be rendered by returning `Html`. Basically, it's a
-component that's been reduced to just the `view` method. On its own that would be quite limiting
-because you can only create pure components, but that's where Hooks come in. Hooks allow function
-components to maintain their own internal state and use other Yew features without needing to manually
-implement the `Component` trait.
+Lets revisit this previous statement:
+
+> Yew mostly operates on the idea of keeping everything that a reusable piece of
+> UI may need, in one place - rust files.
+
+It is only partially correct, "rust files" should be replaced with "components".
+
+## What are Components?
+
+Components are the building blocks of Yew.
+
+They:
+
+- Take arguments in form of [Props](./properties)
+- Can have their own state
+- Get computed into HTML visible to the user (DOM)
+
+## Two flavours of Yew Components
+
+You are currently reading about function components - the recommended way to write components when starting with Yew.
+
+But we have to note that there is a more advanced, but less recommended way to write them - [Struct components](../advanced-topics/struct-components/introduction)
## Creating function components
-The easiest way to create a function component is to add the [`#[function_component]`](./../function-components/attribute.mdx) attribute to a function.
+To create a function component add the `#[function_component]` attribute to a function.
+Also name the function in PascalCase as it is the convention for naming components.
```rust
use yew::{function_component, html, Html};
@@ -22,50 +38,32 @@ use yew::{function_component, html, Html};
fn HelloWorld() -> Html {
html! { "Hello world" }
}
-```
-
-### Under the hood
-
-There are two parts to how Yew implements function components.
-
-The first part is the `FunctionProvider` trait which is analogous to the `Component` trait, except
-that it only has a single method (called `run`). The second part is the `FunctionComponent` struct
-which wraps types implementing `FunctionProvider` and implements `Component`.
-The `#[function_component]` attribute is a procedural macro which automatically implements
-`FunctionProvider` for you and exposes it wrapped in `FunctionComponent`.
+// Then somewhere else you can use the component inside the `html!`
+#[function_component]
+fn App() -> Html {
+ html! {+ { "My name is: " } + { name } +
+
-
-
- }
-}
-```
-
-:::caution
-
-The value held in the handle will reflect the value at the time the
-handle is returned by the `use_state`. It is possible that the handle
-does not dereference to an up to date value if you are moving it into a
-`use_effect_with_deps` hook. You can register the
-state to the dependents so the hook can be updated when the value changes.
-
-:::
-
-## `use_state_eq`
-
-This hook has the same effect as `use_state` but will only trigger a
-re-render when the setter receives a value that `prev_state != next_state`.
-
-This hook requires the state object to implement `PartialEq`.
-
-## `use_memo`
-`use_memo` is used for obtaining an immutable reference to a memoized value.
-Its state persists across renders.
-Its value will be recalculated only if any of the dependencies values change.
-
-`use_memo` can be useful for keeping things in scope for the lifetime of the component, so long as
-you don't store a clone of the resulting `Rc` anywhere that outlives the component.
-
-```rust
-use yew::{function_component, html, use_memo, use_state, Callback, Html, Properties};
-
-#[derive(PartialEq, Properties)]
-pub struct Props {
- pub step: usize,
-}
-
-#[function_component(UseMemo)]
-fn ref_hook(props: &Props) -> Html {
- // Will only get recalculated if `props.step` value changes
- let message = use_memo(
- |step| format!("{}. Do Some Expensive Calculation", step),
- props.step
- );
-
- html! {
- - { "Current value: " } - { *counter } -
-
- { (*message).clone() }
-
- }
-}
-```
-
-## `use_mut_ref`
-`use_mut_ref` is used for obtaining a mutable reference to a value.
-Its state persists across renders.
-
-It is important to note that you do not get notified of state changes.
-If you need the component to be re-rendered on state change, consider using [`use_state`](#use_state).
-
-### Example
-
-```rust
-use web_sys::HtmlInputElement;
-use yew::{
- events::Event,
- function_component, html, use_mut_ref, use_state,
- Callback, TargetCast,
- Html,
-};
-
-#[function_component(UseMutRef)]
-fn mut_ref_hook() -> Html {
- let message = use_state(|| "".to_string());
- let message_count = use_mut_ref(|| 0);
-
- let onclick = Callback::from(move |_| {
- let window = gloo::utils::window();
-
- if *message_count.borrow_mut() > 3 {
- window.alert_with_message("Message limit reached").unwrap();
- } else {
- *message_count.borrow_mut() += 1;
- window.alert_with_message("Message sent").unwrap();
- }
- });
-
- let onchange = {
- let message = message.clone();
- Callback::from(move |e: Event| {
- let input: HtmlInputElement = e.target_unchecked_into();
- message.set(input.value());
- })
- };
-
- html! {
-
-
-
-
- }
-}
-```
-
-## `use_node_ref`
-`use_node_ref` is used for obtaining a `NodeRef` that persists across renders.
-
-When conditionally rendering elements you can use `NodeRef` in conjunction with `use_effect_with_deps`
-to perform actions each time an element is rendered and just before its going to be removed from the
-DOM.
-
-### Example
-
-```rust
-use web_sys::HtmlInputElement;
-use yew::{
- function_component, functional::*, html,
- NodeRef, Html
-};
-
-#[function_component(UseRef)]
-pub fn ref_hook() -> Html {
- let input_ref = use_node_ref();
- let value = use_state(|| 25f64);
-
- let onclick = {
- let input_ref = input_ref.clone();
- let value = value.clone();
- move |_| {
- if let Some(input) = input_ref.cast::
-
-
-
- }
-}
-```
-
-## `use_reducer`
-
-`use_reducer` is an alternative to [`use_state`](#use_state). It is used to handle component's state and is used
-when complex actions needs to be performed on said state.
-
-It accepts an initial state function and returns a `UseReducerHandle` that dereferences to the state,
-and a dispatch function.
-The dispatch function takes one argument of type `Action`. When called, the action and current value
-are passed to the reducer function which computes a new state which is returned,
-and the component is re-rendered.
-
-The dispatch function is guaranteed to be the same across the entire
-component lifecycle. You can safely omit the `UseReducerHandle` from the
-dependents of `use_effect_with_deps` if you only intend to dispatch
-values from within the hooks.
-
-The state object returned by the initial state function is required to
-implement a `Reducible` trait which provides an `Action` type and a
-reducer function.
-
-This hook will always trigger a re-render upon receiving an action. See
-[`use_reducer_eq`](#use_reducer_eq) if you want the component to only
-re-render when the state changes.
-
-### Example
-
-```rust
-use yew::prelude::*;
-use std::rc::Rc;
-
-/// reducer's Action
-enum CounterAction {
- Double,
- Square,
-}
-
-/// reducer's State
-struct CounterState {
- counter: i32,
-}
-
-impl Default for CounterState {
- fn default() -> Self {
- Self { counter: 1 }
- }
-}
-
-impl Reducible for CounterState {
- /// Reducer Action Type
- type Action = CounterAction;
-
- /// Reducer Function
- fn reduce(self: Rc{ counter.counter }
-
-
-
-
- }
-}
-```
-
-:::caution
-
-The value held in the handle will reflect the value of at the time the
-handle is returned by the `use_reducer`. It is possible that the handle does
-not dereference to an up to date value if you are moving it into a
-`use_effect_with_deps` hook. You can register the
-state to the dependents so the hook can be updated when the value changes.
-
-:::
-
-## `use_reducer_eq`
-
-This hook has the same effect as `use_reducer` but will only trigger a
-re-render when the reducer function produces a value that `prev_state != next_state`.
-
-This hook requires the state object to implement `PartialEq` in addition
-to the `Reducible` trait required by `use_reducer`.
-
-## `use_effect`
-
-`use_effect` is used for hooking into the component's lifecycle.
-Similar to `rendered` from the `Component` trait,
-`use_effect` takes a function which is called after the render finishes.
-
-The input function has to return a closure, the destructor, which is called when the component is destroyed.
-The destructor can be used to clean up the effects introduced and it can take ownership of values to delay dropping them until the component is destroyed.
-
-### Example
-
-```rust
-use yew::{Callback, function_component, html, use_effect, use_state, Html};
-
-#[function_component(UseEffect)]
-fn effect() -> Html {
- let counter = use_state(|| 0);
-
- {
- let counter = counter.clone();
- use_effect(move || {
- // Make a call to DOM API after component is rendered
- gloo::utils::document().set_title(&format!("You clicked {} times", *counter));
-
- // Perform the cleanup
- || gloo::utils::document().set_title("You clicked 0 times")
- });
- }
- let onclick = {
- let counter = counter.clone();
- Callback::from(move |_| counter.set(*counter + 1))
- };
-
- html! {
-
- }
-}
-```
-
-### `use_effect_with_deps`
-
-Sometimes, it's needed to manually define dependencies for [`use_effect`](#use_effect). In such cases, we use `use_effect_with_deps`.
-```rust ,no_run
-use yew::use_effect_with_deps;
-
-use_effect_with_deps(
- move |_| {
- // ...
- || ()
- },
- (), // dependents
-);
-```
-
-**Note**: `dependents` must implement `PartialEq`.
-
-## `use_context`
-
-`use_context` is used for consuming [contexts](../contexts.mdx) in function components.
-
-
-### Example
-
-```rust
-use yew::{ContextProvider, function_component, html, use_context, use_state, Html};
-
-
-/// App theme
-#[derive(Clone, Debug, PartialEq)]
-struct Theme {
- foreground: String,
- background: String,
-}
-
-/// Main component
-#[function_component(App)]
-pub fn app() -> Html {
- let ctx = use_state(|| Theme {
- foreground: "#000000".to_owned(),
- background: "#eeeeee".to_owned(),
- });
-
- html! {
- // `ctx` is type `Rc
-
- }
-}
-
-/// Button placed in `Toolbar`.
-/// As this component is a child of `ThemeContextProvider` in the component tree, it also has access to the context.
-#[function_component(ThemedButton)]
-pub fn themed_button() -> Html {
- let theme = use_context::