leptos_use/
use_throttle_fn.rs

1use crate::utils::{create_filter_wrapper, create_filter_wrapper_with_arg, throttle_filter};
2use leptos::prelude::Signal;
3use std::sync::{Arc, Mutex};
4
5pub use crate::utils::ThrottleOptions;
6
7/// Throttle execution of a function.
8/// Especially useful for rate limiting execution of handlers on events like resize and scroll.
9///
10/// > Throttle is a spring that throws balls: After a ball flies out it needs some time to shrink back, so it cannot throw any more balls until it's ready.
11///
12/// ## Demo
13///
14/// [Link to Demo](https://github.com/Synphonyte/leptos-use/tree/main/examples/use_throttle_fn)
15///
16/// ## Usage
17///
18/// ```
19/// # use leptos::prelude::*;
20/// # use leptos_use::use_throttle_fn;
21/// #
22/// # #[component]
23/// # fn Demo() -> impl IntoView {
24/// let mut throttled_fn = use_throttle_fn(
25///     || {
26///         // do something, it will be called at most 1 time per second
27///     },
28///     1000.0,
29/// );
30/// view! {
31///     <button on:click=move |_| { throttled_fn(); }>
32///         "Smash me!"
33///     </button>
34/// }
35/// # }
36/// ```
37///
38/// Please note that if the current component is cleaned up before the throttled callback is called, the throttled callback will not be called.
39///
40/// You can provide options when you use [`use_throttle_fn_with_options`].
41///
42/// ```
43/// # use leptos::prelude::*;
44/// # use leptos_use::{ThrottleOptions, use_throttle_fn_with_options};
45/// # #[component]
46/// # fn Demo() -> impl IntoView {
47/// let throttled_fn = use_throttle_fn_with_options(
48///     || {
49///         // do something, it will be called at most 1 time per second
50///     },
51///     1000.0,
52///     ThrottleOptions::default()
53///         .leading(true)
54///         .trailing(true),
55/// );
56/// #    view! { }
57/// # }
58/// ```
59///
60/// If you want to throttle a function that takes an argument there are also the versions
61/// [`use_throttle_fn_with_arg`] and [`use_throttle_fn_with_arg_and_options`].
62///
63/// ## SendWrapped Return
64///
65/// The returned closure is a sendwrapped function. It can
66/// only be called from the same thread that called `use_throttle_...`.
67///
68/// ## Recommended Reading
69///
70/// - [**Debounce vs Throttle**: Definitive Visual Guide](https://redd.one/blog/debounce-vs-throttle)
71/// - [Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/)
72///
73/// ## Server-Side Rendering
74///
75/// Internally this uses `setTimeout` which is not supported on the server. So usually calling
76/// a throttled function on the server will simply be ignored.
77pub fn use_throttle_fn<F, R>(
78    func: F,
79    ms: impl Into<Signal<f64>> + 'static,
80) -> impl Fn() -> Arc<Mutex<Option<R>>> + Clone + Send + Sync
81where
82    F: Fn() -> R + Clone + 'static,
83    R: 'static,
84{
85    use_throttle_fn_with_options(func, ms, Default::default())
86}
87
88/// Version of [`use_throttle_fn`] with throttle options. See the docs for [`use_throttle_fn`] for how to use.
89pub fn use_throttle_fn_with_options<F, R>(
90    func: F,
91    ms: impl Into<Signal<f64>> + 'static,
92    options: ThrottleOptions,
93) -> impl Fn() -> Arc<Mutex<Option<R>>> + Clone + Send + Sync
94where
95    F: Fn() -> R + Clone + 'static,
96    R: 'static,
97{
98    create_filter_wrapper(Arc::new(throttle_filter(ms, options)), func)
99}
100
101/// Version of [`use_throttle_fn`] with an argument for the throttled function. See the docs for [`use_throttle_fn`] for how to use.
102pub fn use_throttle_fn_with_arg<F, Arg, R>(
103    func: F,
104    ms: impl Into<Signal<f64>> + 'static,
105) -> impl Fn(Arg) -> Arc<Mutex<Option<R>>> + Clone + Send + Sync
106where
107    F: Fn(Arg) -> R + Clone + 'static,
108    Arg: Clone + 'static,
109    R: 'static,
110{
111    use_throttle_fn_with_arg_and_options(func, ms, Default::default())
112}
113
114/// Version of [`use_throttle_fn_with_arg`] with throttle options. See the docs for [`use_throttle_fn`] for how to use.
115pub fn use_throttle_fn_with_arg_and_options<F, Arg, R>(
116    func: F,
117    ms: impl Into<Signal<f64>> + 'static,
118    options: ThrottleOptions,
119) -> impl Fn(Arg) -> Arc<Mutex<Option<R>>> + Clone + Send + Sync
120where
121    F: Fn(Arg) -> R + Clone + 'static,
122    Arg: Clone + 'static,
123    R: 'static,
124{
125    create_filter_wrapper_with_arg(Arc::new(throttle_filter(ms, options)), func)
126}
leptos_use/use_throttle_fn.rs

leptos_use/
use_throttle_fn.rs
