@@ -65,7 +65,42 @@ re-render when the setter receives a value that `prev_state != next_state`.
6565This hook requires the state object to implement ` PartialEq ` .
6666
6767## ` use_ref `
68- ` use_ref ` is used for obtaining a mutable reference to a value.
68+ ` use_ref ` is used for obtaining an immutable reference to a value.
69+ Its state persists across renders.
70+
71+ ` use_ref ` can be useful for keeping things in scope for the lifetime of the component, so long as
72+ you don't store a clone of the resulting ` Rc ` anywhere that outlives the component.
73+
74+ If you need a mutable reference, consider using [ ` use_mut_ref ` ] ( #use_mut_ref ) .
75+ If you need the component to be re-rendered on state change, consider using [ ` use_state ` ] ( #use_state ) .
76+
77+ ``` rust
78+ // EventBus is an implementation of yew_agent::Agent
79+ use website_test :: agents :: EventBus ;
80+ use yew :: {function_component, html, use_ref, use_state, Callback };
81+ use yew_agent :: Bridged ;
82+
83+ #[function_component(UseRef )]
84+ fn ref_hook () -> Html {
85+ let greeting = use_state (|| " No one has greeted me yet!" . to_owned ());
86+
87+ {
88+ let greeting = greeting . clone ();
89+ use_ref (|| EventBus :: bridge (Callback :: from (move | msg | {
90+ greeting . set (msg );
91+ })));
92+ }
93+
94+ html! {
95+ <div >
96+ <span >{ (* greeting ). clone () }</ span >
97+ </ div >
98+ }
99+ }
100+ ```
101+
102+ ## ` use_mut_ref `
103+ ` use_mut_ref ` is used for obtaining a mutable reference to a value.
69104Its state persists across renders.
70105
71106It is important to note that you do not get notified of state changes.
@@ -77,14 +112,14 @@ If you need the component to be re-rendered on state change, consider using [`us
77112use web_sys :: HtmlInputElement ;
78113use yew :: {
79114 events :: Event ,
80- function_component, html, use_ref , use_state,
115+ function_component, html, use_mut_ref , use_state,
81116 Callback , TargetCast ,
82117};
83118
84- #[function_component(UseRef )]
85- fn ref_hook () -> Html {
119+ #[function_component(UseMutRef )]
120+ fn mut_ref_hook () -> Html {
86121 let message = use_state (|| "" . to_string ());
87- let message_count = use_ref (|| 0 );
122+ let message_count = use_mut_ref (|| 0 );
88123
89124 let onclick = Callback :: from (move | _ | {
90125 let window = gloo_utils :: window ();
@@ -114,6 +149,46 @@ fn ref_hook() -> Html {
114149}
115150```
116151
152+ ## ` use_node_ref `
153+ ` use_node_ref ` is used for obtaining a ` NodeRef ` that persists across renders.
154+
155+ When conditionally rendering elements you can use ` NodeRef ` in conjunction with ` use_effect_with_deps `
156+ to perform actions each time an element is rendered and just before its going to be removed from the
157+ DOM.
158+
159+ ### Example
160+
161+ ``` rust
162+ use web_sys :: HtmlInputElement ;
163+ use yew :: {
164+ function_component, functional :: * , html,
165+ NodeRef
166+ };
167+
168+ #[function_component(UseRef )]
169+ pub fn ref_hook () -> Html {
170+ let input_ref = use_node_ref ();
171+ let value = use_state (|| 25f64 );
172+
173+ let onclick = {
174+ let input_ref = input_ref . clone ();
175+ let value = value . clone ();
176+ move | _ | {
177+ if let Some (input ) = input_ref . cast :: <HtmlInputElement >() {
178+ value . set (* value + input . value_as_number ());
179+ }
180+ }
181+ };
182+
183+ html! {
184+ <div >
185+ <input ref = {input_ref } type = " number" / >
186+ <button {onclick }>{ format! (" Add input to {}" * value ) }</ button >
187+ </ div >
188+ }
189+ }
190+ ```
191+
117192## ` use_reducer `
118193
119194` use_reducer ` is an alternative to [ ` use_state ` ] ( #use_state ) . It is used to handle component's state and is used
0 commit comments