Pre-defined Hooks
use_state
use_state
is used to manage state in a function component.
It returns a UseStateHandle
object which Deref
s to the current value
and provides a set
method to update the value.
The hook takes a function as input which determines the initial state. This value remains up-to-date on subsequent renders.
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
if you want the component to only
re-render when the state changes.
Example
use yew::{Callback, function_component, html, use_state};
#[function_component(UseState)]
fn state() -> Html {
let counter = use_state(|| 0);
let onclick = {
let counter = counter.clone();
Callback::from(move |_| counter.set(*counter + 1))
};
html! {
<div>
<button {onclick}>{ "Increment value" }</button>
<p>
<b>{ "Current value: " }</b>
{ *counter }
</p>
</div>
}
}
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_ref
use_ref
is used for obtaining an immutable reference to a value.
Its state persists across renders.
use_ref
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.
If you need a mutable reference, consider using use_mut_ref
.
If you need the component to be re-rendered on state change, consider using use_state
.
// EventBus is an implementation of yew_agent::Agent
use website_test::agents::EventBus;
use yew::{function_component, html, use_ref, use_state, Callback};
use yew_agent::Bridged;
#[function_component(UseRef)]
fn ref_hook() -> Html {
let greeting = use_state(|| "No one has greeted me yet!".to_owned());
{
let greeting = greeting.clone();
use_ref(|| EventBus::bridge(Callback::from(move |msg| {
greeting.set(msg);
})));
}
html! {
<div>
<span>{ (*greeting).clone() }</span>
</div>
}
}
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
.
Example
use web_sys::HtmlInputElement;
use yew::{
events::Event,
function_component, html, use_mut_ref, use_state,
Callback, TargetCast,
};
#[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! {
<div>
<input {onchange} value={(*message).clone()} />
<button {onclick}>{ "Send" }</button>
</div>
}
}
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
use web_sys::HtmlInputElement;
use yew::{
function_component, functional::*, html,
NodeRef
};
#[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::<HtmlInputElement>() {
value.set(*value + input.value_as_number());
}
}
};
html! {
<div>
<input ref={input_ref} type="number" />
<button {onclick}>{ format!("Add input to {}", *value) }</button>
</div>
}
}
use_reducer
use_reducer
is an alternative to 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
if you want the component to only
re-render when the state changes.
Example
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<Self>, action: Self::Action) -> Rc<Self> {
let next_ctr = match action {
CounterAction::Double => self.counter * 2,
CounterAction::Square => self.counter.pow(2)
};
Self { counter: next_ctr }.into()
}
}
#[function_component(UseReducer)]
fn reducer() -> Html {
// The use_reducer hook takes an initialization function which will be called only once.
let counter = use_reducer(CounterState::default);
let double_onclick = {
let counter = counter.clone();
Callback::from(move |_| counter.dispatch(CounterAction::Double))
};
let square_onclick = {
let counter = counter.clone();
Callback::from(move |_| counter.dispatch(CounterAction::Square))
};
html! {
<>
<div id="result">{ counter.counter }</div>
<button onclick={double_onclick}>{ "Double" }</button>
<button onclick={square_onclick}>{ "Square" }</button>
</>
}
}
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
use yew::{Callback, function_component, html, use_effect, use_state};
#[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! {
<button {onclick}>{ format!("Increment to {}", *counter) }</button>
}
}
use_effect_with_deps
Sometimes, it's needed to manually define dependencies for use_effect
. In such cases, we use use_effect_with_deps
.
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 in function components.
Example
use yew::{ContextProvider, function_component, html, use_context, use_state};
/// 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<UseStateHandle<Theme>>` while we need `Theme`
// so we deref it.
// It derefs to `&Theme`, hence the clone
<ContextProvider<Theme> context={(*ctx).clone()}>
// Every child here and their children will have access to this context.
<Toolbar />
</ContextProvider<Theme>>
}
}
/// The toolbar.
/// This component has access to the context
#[function_component(Toolbar)]
pub fn toolbar() -> Html {
html! {
<div>
<ThemedButton />
</div>
}
}
/// 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::<Theme>().expect("no ctx found");
html! {
<button style={format!("background: {}; color: {};", theme.background, theme.foreground)}>
{ "Click me!" }
</button>
}
}