Get Started
Installation
cargo add leptos-use
Examples
Usage Example
Simply import the functions you need from leptos-use
use leptos::*;
use leptos_use::{use_mouse, UseMouseReturn};
#[component]
fn Demo() -> impl IntoView {
let UseMouseReturn { x, y, .. } = use_mouse();
view! { cx,
{x} " x " {y}
}
}
Please refer to the functions list for more details.
Stable Rust
Just like leptos
this library can be safely run on stable rust.
In the Getting Started section
of the leptos
docs you can read more about what this means.
Element Parameters
Many functions in this library operate on HTML/SVG elements. For example, the
function use_element_size
returns the width and height of an element:
#![allow(unused)] fn main() { use leptos::{*, html::Div}; use leptos_use::{use_element_size, UseElementSizeReturn}; #[component] pub fn Component() -> impl IntoView { let el = create_node_ref::<Div>(); let UseElementSizeReturn { width, height } = use_element_size(el); view! { <div node_ref=el></div> } } }
In the example above we used a Leptos NodeRef
to pass into the function. But that is not
the only way you can do that. All of these work as well:
#![allow(unused)] fn main() { use_element_size(window().body()); // Option<web_sys::Element> use_element_size(window().body().unwrap()); // web_sys::Element use_element_size("div > p.some-class"); // &str or String intepreted as CSS selector pub fn some_directive(el: HtmlElement<AnyElement>) { use_element_size(el); // leptos::html::HtmlElement<T> } }
Signal of Strings: Signal<String>
, ReadSignal<String>
, RwSignal<String>
, Memo<String>
; also works with &str
:
#![allow(unused)] fn main() { let (str_signal, set_str_signal) = create_signal("div > p.some-class".to_string()); use_element_size(str_signal); }
Signals of Elements: Signal<web_sys::Element>
, ReadSignal<web_sys::Element>
, RwSignal<web_sys::Element>
, Memo<web_sys::Element>
; also works with Option<web_sys::Element>
:
#![allow(unused)] fn main() { let (el_signal, set_el_signal) = create_signal(document().query_selector("div > p.some-class").unwrap()); use_element_size(el_signal); }
How it works
Looking at the source code of use_element_size
you'll find sth like
#![allow(unused)] fn main() { pub fn use_element_size(el: Into<ElementMaybeSignal<...>>) -> UseElementSizeReturn {} }
All the above code works because there are From
implementations for all of these
types for ElementMaybeSignal
.
ElementsMaybeSignal
Some functions work on one or more elements. Take use_resize_observer
for example.
This works very much the same way as described above but instead of Into<ElementMaybeSignal>
it takes an Into<ElementsMaybeSignal>
(note the plural). This means you can use it exactly in
the same ways as you saw with the singular ElementMaybeSignal
. Only this time, when you use
String
or &str
it will be interpreted as CSS selector with query_selector_all
.
But you can also use it with containers.
#![allow(unused)] fn main() { // Array of Option<web_sys::Element> use_resize_observer([window().body(), document().query_selector("div > p.some-class").unsrap()]); // Vec of &str. All of them will be interpreted as CSS selectors with query_selector_all() and the // results will be merged into one Vec. use_resize_observer(vec!["div > p.some-class", "p.some-class"]); // Slice of NodeRef let node_ref1 = create_node_ref::<Div>(); let node_ref2 = create_node_ref::<Div>(); use_resize_observer(vec![node_ref1, node_ref2].as_slice()); }
Usage in Options
Some functions have options that take Element(s)MaybeSignal
.
They can be used in the same way.
#![allow(unused)] fn main() { use_mouse_with_options( UseMouseOptions::default().target("div > p.some-class") ); }
See also "Excluding Elements" in on_click_outside
.
Server-Side Rendering
When using together with server-side rendering (SSR) you have to enable the feature ssr
similar to
how you do it for leptos
.
In your Cargo.toml file enable Leptos-Use's ssr
feature only from your project's ssr
feature:
[dependencies]
leptos-use = "0.10" # do NOT enable the "ssr" feature here
...
[features]
hydrate = [
"leptos/hydrate",
...
]
ssr = [
...
"leptos/ssr",
...
"leptos-use/ssr" # <== add this
]
...
Please see the ssr
example in the examples folder
for a simple working demonstration.
Many functions work differently on the server and on the client. If that's the case you will find information about these differences in their respective docs under the section "Server-Side Rendering". If you don't find that section, it means that the function works exactly the same on both, the client and the server.
Do not enable the
ssr
feature directly!Don't do the following.
[dependencies] leptos-use = { version = "0.10", features = ["ssr"] } # this is wrong
The ssr
feature is used to select which version of the functions are built.
Effectively it means your application is built two times: with ssr
enabled to
build the server executable, and with ssr
disabled to build the client's WASM
binary module.
So if you enable leptos-use
's ssr
feature globally, you will get the server
version of the functions in the client.
By adding "leptos-use/ssr"
to the ssr
feature of your project, it will only
be enabled when your project is built with ssr
, and you will get the server
functions server-side, and the client functions client-side.
WASM on the server
If you enable ssr
in your project on a wasm32
target architecture, you will get
a compile-time warning in the console because it is a common mistake that users enable ssr
globally.
If you're using wasm32
on the server however you can safely disable this warning by
enabling the wasm_ssr
feature together with ssr
.
Functions with Target Elements
A lot of functions like use_resize_observer
and use_element_size
are only useful when a target HTML/SVG element is
available. This is not always the case on the server. If you use them with NodeRefs
they will just work in SSR.
But what if you want to use them with window()
or document()
?
To enable that we provide the helper functions use_window()
and use_document()
which return
a new-type-wrapped Option<web_sys::Window>
or Option<web_sys::Document>
respectively. These can be
used safely on the server. The following code works on both the client and the server:
#![allow(unused)] fn main() { use leptos::*; use leptos::ev::keyup; use leptos_use::{use_event_listener, use_window}; use_event_listener(use_window(), keyup, | evt| { ... }); }
There are some convenience methods provided as well, like use_document().body()
which
just propagate a None
on the server.
Changelog
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[0.10.10] - 2024-05-10
Change π₯
- Added compile-time warning when you use
ssr
feature withwasm32
. You can enablewasm_ssr
to remove the warning.
[0.10.9] - 2024-04-27
Fixes π
- Fixed
use_color_mode
without cookies and make cookies sync properly with local storage - Fixed
use_infinite_scroll
edge case bug with disposed signals
[0.10.8] - 2024-04-19
Change π₯
use_cookie
now supports Spin out of the box (thanks to @javierEd).
[0.10.7] - 2024-04-10
New Function π
sync_signal
Change π₯
use_color_mode
now supports cookies.
[0.10.6] - 2024-04-02
Fixes π
- Corrected docs of
use_cookie
'smax-age
unit to milliseconds (thanks to @sify21). - Fixed setting multiple cookies in the browser (thanks to @sbking).
[0.10.5] - 2024-03-12
Fix π
- Fixed SSR detection from an url query parameter for
use_color_mode
(thanks to @mondeja).
[0.10.4] - 2024-03-05
New Functions π
use_event_source
Changes π₯
- Wrapped callbacks in a non-reactive zone to remove potential warnings.
- Updated SSR chapter in the book to make it more clear and beginner-friendly (thanks to @flupke).
[0.10.3] - 2024-02-23
New Functions π
use_or
use_and
use_not
Fix π
- Removed signal warnings from
use_websocket
'ssend...
methods.
Changes π₯
use_color_mode
now supports detection from an url query parameter. (thanks to @mondeja)
[0.10.2] - 2024-02-09
New Functions π
use_permission
use_clipboard
use_timeout_fn
[0.10.1] - 2024-01-31
Fix π
- Fixed docs.rs build
[0.10.0] - 2024-01-31
New Functions π
use_broadcast_channel
use_cookie
(thanks to @rakshith-ravi)use_mouse_in_element
use_device_orientation
(thanks to @mondeja)use_device_pixel_ratio
(thanks to @mondeja)use_element_bounding
Breaking Changes π
- The
leptos
version is now 0.6 - The trait
Codec
has been renamed toStringCodec
and has been moved toutil::StringCodec
.- The struct
StringCodec
has been renamed toFromToStringCodec
and has been moved toutil::FromToStringCodec
. - The structs
JsonCodec
andProstCodec
have been moved toutil
as well.
- The struct
- The function
use_storage
now requires type parameters for the stored type and the codec like all the other...storage...
functions.
Fixes π
- Fixed
use_geolocation
SSR compile issue - Fixed
use_intl_number_format
maximum fraction digits option
Changes π₯
- The
UseMouseReturn
signalsx
,y
, andsource_type
are now of typeSignal<f64>
instead ofReadSignal<f64>
. - You can now convert
leptos::html::HtmlElement<T>
intoElement(s)MaybeSignal
. This should make functions a lot easier to use in directives. - There's now a chapter in the book especially for
Element(s)MaybeSignal
. - Throttled or debounced callbacks (in watch_* or *_fn) no longer are called after the containing scope was cleaned up.
- The document returned from
use_document
now supports the methodsquery_selector
andquery_selector_all
.
[0.9.0] - 2023-12-06
New Functions π
use_display_media
(thanks to @seanaye)
Breaking Changes π
- (@feral-dot-io) The use
use_<type>_storage
functions have been rewritten to useCodec
s instead of always requiringserde
.- This also removes the feature
storage
- By default the
StringCodec
is used which relies on types implementingFromString + ToString
- If you want to use
JsonCodec
you have to enable the featureserde
- If you want to use
ProstCodec
(new!) you have to enable the featureprost
.
- This also removes the feature
- (@feral-dot-io) The Rust flag
--cfg=web_sys_unstable_apis
is not needed anymore since relevantweb_sys
APIs are now stable. This affects in particularuse_element_size
use_resize_observer
Fixes π
use_raf_fn
anduse_timestamp
no longer spam warnings because ofget
ting signals outside of reactive contexts.use_infinite_scroll
no longer calls the callback twice for the same eventuse_scroll
now usestry_get_untracked
in the debounced callback to avoid panics if the context has been destroyed while the callback was waiting to be called.use_idle
works properly now (no more idles too early).use_web_notification
doesn't panic on the server anymore.
[0.8.2] - 2023-11-09
Fixes π
- Fixed SSR for
- use_timestamp
- use_raf_fn
- use_idle
[0.8.1] - 2023-10-28
Fixes π
- Using strings for
ElementMaybeSignal
andElementsMaybeSignal
is now SSR safe.- This fixes specifically
use_color_mode
to work on the server.
- This fixes specifically
[0.8.0] - 2023-10-24
New Functions π
use_web_notification
(thanks to @centershocks44)use_infinite_scroll
use_service_worker
(thanks to @lpotthast)
Breaking Changes π
use_scroll
returnsimpl Fn(T) + Clone
instead ofBox<dyn Fn(T)>
.
Other Changes π₯
UseScrollReturn
is now documented
[0.7.2] - 2023-10-21
Fixes π
- Some functions still used
window()
which could lead to panics in SSR. This is now fixed. Specifically foruse_draggable
.
[0.7.1] - 2023-10-02
New Function π
use_sorted
[0.7.0] - 2023-09-30
New Functions π
use_timestamp
use_idle
use_document
use_window
use_geolocation
signal_debounced
signal_throttled
Breaking Changes π
- Leptos version is now 0.5
- No
cx: Scope
params are supported/needed anymore because of the changes in Leptos. Please check the release notes of Leptos 0.5 for how to upgrade. watch
is now deprecated in favor ofleptos::watch
and will be removed in a future release.watch_with_options
will continue to exist.use_event_listener_with_options
now takes aUseEventListenerOptions
instead of aweb_sys::AddEventListenerOptions
.use_mutation_observer_with_options
now takes aUseMutationObserverOptions
instead of aweb_sys::MutationObserverInit
.use_websocket
:- takes now a
&str
instead of aString
as itsurl
parameter. - same for the returned
send
method. - The
ready_state
return type is now renamed toConnectionReadyState
instead ofUseWebSocketReadyState
. - The returned signals
ready_state
,message
,message_bytes
have now the typeSignal<...>
instead ofReadSignal<...>
to make them more consistent with other functions. - The options
reconnect_limit
andreconnect_interval
now take au64
instead ofOption<u64>
to improve DX. - The option
manual
has been renamed toimmediate
to make it more consistent with other functions. To port please note thatimmediate
is the inverse ofmanual
(immediate
=!manual
). - Added documentation how pass it ergonomically as context.
- takes now a
use_color_mode
:- The optional
on_changed
handler parameters have changed slightly. Please refer to the docs for more details.
- The optional
- Throttled or debounced functions cannot be
FnOnce
anymore. - All traits
ClonableFn...
have been removed.
Other Changes π₯
use_websocket
can use relative urls now- Callbacks in options don't require to be cloneable anymore
- Callback in
use_raf_fn
doesn't require to be cloneable anymore - All (!) functions can now be safely called on the server. Specifically this includes the following that before
panicked on the server:
use_scroll
use_event_listener
use_element_hover
on_click_outside
use_drop_zone
use_element_size
use_element_visibility
use_resize_observer
use_intersection_observer
use_mutation_observer
Fixes π
use_element_visibility
didn't work in some cases on Chrome properly. This has been fixed.
[0.6.3] - 2023-08-12
Fixes π
use_websocket
panicked after unmount
[0.6.2] - 2023-08-03
Fixes π
use_event_listener_with_options
removes the handlers now correctly.
[0.6.1] - 2023-08-03
Fixes π
use_storage
now uses.get_untracked()
to avoid warnings.
[0.6.0] - 2023-07-17
New Functions π
use_draggable
use_to_string
is_err
is_ok
is_none
is_some
use_raf_fn
Breaking Changes π
- The following functions now accept a
MaybeRwSignal
as their initial/default value which means you can use a synchronizedRwSignal
in those places.use_color_mode
use_cycle_list
use_favicon
use_storage
use_local_storage
use_session_storage
- Instead of returning
ReadSignal
, the following functions now returnSignal
.use_color_mode
use_favicon
use_storage
use_local_storage
use_session_storage
Fixes π
use_drop_zone
now uses.get_untracked()
in event handlers
[0.5.0] - 2023-07-15
New Functions π
use_drop_zone
use_websocket
(thanks @sectore)use_intl_number_format
Changes π₯
- Crate is ready for Server-Side Rendering. Enable feature
ssr
like you do forleptos
.
[0.4.1] - 2023-07-07
New Functions π
use_window_focus
use_window_scroll
use_document_visibility
[0.4.0] - 2023-07-03
Breaking Changes π
- Required
leptos
version is now 0.4 - Following the changes in
leptos
there is no longer astable
crate feature required in order to use this library with a stable toolchain. If you want to use it with a nightly toolchain you have to enable thenightly
feature only onleptos
directly. No change is required forleptos-use
itself.
[0.3.3] - 2023-06-24
New Functions π
use_color_mode
use_cycle_list
use_active_element
Changes π₯
- You can now use this crate with the
stable
toolchain (thanks @lpotthast) - Set leptos dependency to
default-features = false
in order to enable SSR.
[0.3.2] - 2023-06-17
New Functions π
use_css_var
use_element_hover
[0.3.1] - 2023-06-15
New Functions π
use_interval_fn
use_interval
[0.3.0] - 2023-06-13
Breaking Changes π
use_event_listener
no longer returns aBox<dyn Fn()>
but aimpl Fn() + Clone
Changes π₯
- You can now specify a
&str
orSignal<String>
with CSS selectors wherever a node ref is accepted - Callbacks of the following functions no longer require
Clone
use_resize_observer
use_intersection_observer
- These functions now also accept multiple target elements in addition to a single one:
use_resize_observer
use_intersection_observer
New Functions π
whenever
use_mutation_observer
use_abs
on_click_outside
[0.2.1] - 2023-06-11
New Functions
use_intersection_observer
use_element_visibility
[0.2.0] - 2023-06-11
Breaking Changes
watch
doesn't acceptimmediate
as a direct argument anymore. This is only provided by the option variant.watch
has now variantwatch_with_options
which allows for debouncing and throttling.
New Functions
use_storage
use_local_storage
use_session_storage
watch_debounced
watch_throttled
watch_pausable
use_ceil
use_round
use_media_query
use_preferred_dark
use_preferred_contrast
use_favicon
use_breakpoints
Other Changes
- Function count badge in readme
[0.1.8/9] - 2023-06-05
- Fixed documentation and doc tests running for functions behind
#[cfg(web_sys_unstable_apis)]
[0.1.7] - 2023-06-05
New Function
use_element_size
[0.1.6] - 2023-06-03
Changes
- Fixed documentation so all feature are documented
[0.1.5] - 2023-06-03
New Functions
use_floor
use_max
use_min
Changes
- New feature:
math
that has to be activated in order to use the math functions.
[0.1.4] - 2023-06-02
New Functions
use_supported
use_resize_observer
watch
use_mouse
Changes
- Use the crate
default-struct-builder
to provide ergonimic function options.
[0.1.3] - 2023-05-28
New Functions
use_scroll
use_debounce_fn
Other Changes
- Better and more beautiful demo integration into the guide.
Functions
Storage
- use_local_storage β Reactive LocalStorage.
- use_session_storage β Reactive SessionStorage.
- use_storage β Reactive Storage.
Elements
- use_active_element β Reactive
document.activeElement
- use_document β SSR safe
document()
. - use_document_visibility β Reactively track
document.visibilityState
- use_draggable β Make elements draggable.
- use_drop_zone β Create a zone where files can be dropped.
- use_element_bounding β Reactive bounding box of an HTML element
- use_element_size β Reactive size of an HTML element.
- use_element_visibility β Tracks the visibility of an element within the viewport.
- use_intersection_observer β Reactive IntersectionObserver.
- use_mouse_in_element β Reactive mouse position related to an element.
- use_mutation_observer β Reactive MutationObserver.
- use_resize_observer β Reports changes to the dimensions of an Element's content or the border-box.
- use_window β SSR safe
window()
. - use_window_focus β Reactively track window focus
- use_window_scroll β Reactive window scroll.
Browser
- use_breakpoints β Reactive viewport breakpoints.
- use_broadcast_channel β Reactive BroadcastChannel API.
- use_clipboard β Reactive Clipboard API.
- use_color_mode β Reactive color mode (dark / light / customs) with auto data persistence.
- use_cookie β SSR-friendly and reactive cookie access.
- use_css_var β Manipulate CSS variables.
- use_display_media β Reactive
mediaDevices.getDisplayMedia
streaming. - use_event_listener β Use EventListener with ease.
- use_favicon β Reactive favicon.
- use_media_query β Reactive Media Query.
- use_permission β Reactive Permissions API.
- use_preferred_contrast β Reactive prefers-contrast media query.
- use_preferred_dark β Reactive dark theme preference.
- use_service_worker β Reactive ServiceWorker API.
- use_web_notification β Reactive Notification API.
Intl
- use_intl_number_format β Reactive
Intl.NumberFormat
.
Sensors
- on_click_outside β Listen for clicks outside of an element.
- use_device_orientation β Reactive DeviceOrientationEvent.
- use_device_pixel_ratio β Reactive
window.devicePixelRatio
- use_element_hover β Reactive element's hover state.
- use_geolocation β Reactive Geolocation API.
- use_idle β ///
- use_infinite_scroll β Infinite scrolling of the element.
- use_mouse β Reactive mouse position
- use_scroll β We have to check if the scroll amount is close enough to some threshold in order to
Network
- use_event_source β Reactive EventSource
- use_websocket β Creating and managing a Websocket connection.
Animation
- use_interval β Reactive counter increases on every interval.
- use_interval_fn β Wrapper for
set_interval
with controls. - use_raf_fn β Call function on every requestAnimationFrame.
- use_timeout_fn β Wrapper for
setTimeout
with controls. - use_timestamp β Reactive current timestamp.
Watch
- watch_debounced β A debounced version of [
watch
]. - watch_pausable β Pausable [
watch
]. - watch_throttled β A throttled version of [
watch
]. - watch_with_options β A version of
leptos::watch
but with additional options. - whenever β Shorthand for watching a signal to be
true
.
Utilities
- is_err β Reactive
Result::is_err()
. - is_none β Reactive
Option::is_none()
. - is_ok β Reactive
Result::is_ok()
. - is_some β Reactive
Option::is_some()
. - use_cycle_list β Cycle through a list of items.
- use_debounce_fn β Debounce execution of a function.
- use_supported β SSR compatibe
is_supported
- use_throttle_fn β Throttle execution of a function.
- use_to_string β Reactive
ToString::to_string()
.
Math
- use_abs β Reactive
abs()
. - use_and β Reactive
AND
condition. - use_ceil β Reactive
ceil()
. - use_floor β Reactive
floor()
. - use_max β Reactive
max()
. - use_min β Reactive
min()
. - use_not β Reactive
NOT
condition. - use_or β Reactive
OR
condition. - use_round β Reactive
round()
.
use_local_storage
Reactive LocalStorage.
LocalStorage stores data in the browser with no expiration time. Access is given to all pages from the same origin (e.g., all pages from "https://example.com" share the same origin). While data doesn't expire the user can view, modify and delete all data stored. Browsers allow 5MB of data to be stored.
This is contrast to use_session_storage
which clears data when the page session ends and is not shared.
Usage
See use_storage
for more details on how to use.
Source
use_session_storage
Reactive SessionStorage.
SessionStorages stores data in the browser that is deleted when the page session ends. A page session ends when the browser closes the tab. Data is not shared between pages. While data doesn't expire the user can view, modify and delete all data stored. Browsers allow 5MB of data to be stored.
Use use_local_storage
to store data that is shared amongst all pages with the same origin and persists between page sessions.
Usage
See use_storage
for more details on how to use.
Source
use_storage
Reactive Storage.
The function returns a triplet (read_signal, write_signal, delete_from_storage_fn)
.
Demo
Usage
Pass a StorageType
to determine the kind of key-value browser storage to use.
The specified key is where data is stored. All values are stored as UTF-16 strings which
is then encoded and decoded via the given Codec
. This value is synced with other calls using
the same key on the smae page and across tabs for local storage.
See UseStorageOptions
to see how behaviour can be further customised.
See StringCodec
for more details on how to handle versioning β dealing with data that can outlast your code.
To use the
JsonCodec
, you will need to add the"serde"
feature to your project'sCargo.toml
. To useProstCodec
, add the feature"prost"
.
Example
use leptos::*;
use leptos_use::storage::{StorageType, use_local_storage, use_session_storage, use_storage};
use serde::{Deserialize, Serialize};
use leptos_use::utils::{FromToStringCodec, JsonCodec, ProstCodec};
pub fn Demo() -> impl IntoView {
// Binds a struct:
let (state, set_state, _) = use_local_storage::<MyState, JsonCodec>("my-state");
// Binds a bool, stored as a string:
let (flag, set_flag, remove_flag) = use_session_storage::<bool, FromToStringCodec>("my-flag");
// Binds a number, stored as a string:
let (count, set_count, _) = use_session_storage::<i32, FromToStringCodec>("my-count");
// Binds a number, stored in JSON:
let (count, set_count, _) = use_session_storage::<i32, JsonCodec>("my-count-kept-in-js");
// Bind string with SessionStorage stored in ProtoBuf format:
let (id, set_id, _) = use_storage::<String, ProstCodec>(
StorageType::Session,
"my-id",
);
view! { }
}
// Data stored in JSON must implement Serialize, Deserialize.
// And you have to add the feature "serde" to your project's Cargo.toml
#[derive(Serialize, Deserialize, Clone, PartialEq)]
pub struct MyState {
pub hello: String,
pub greeting: String,
}
// Default can be used to implement initial or deleted values.
// You can also use a signal via UseStorageOptions::default_value`
impl Default for MyState {
fn default() -> Self {
Self {
hello: "hi".to_string(),
greeting: "Hello".to_string()
}
}
}
Create Your Own Custom Codec
All you need to do is to implement the StringCodec
trait together with Default
and Clone
.
Server-Side Rendering
On the server the returned signals will just read/manipulate the initial_value
without persistence.
Types
Source
use_active_element
Reactive document.activeElement
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::use_active_element;
#[component]
fn Demo() -> impl IntoView {
let active_element = use_active_element();
create_effect(move |_| {
log!("focus changed to {:?}", active_element.get());
});
view! { }
}
Server-Side Rendering
On the server this returns a Signal
that always contains the value None
.
Source
use_document
SSR safe document()
.
This returns just a new-type wrapper around Option<Document>
.
Calling this amounts to None
on the server and Some(Document)
on the client.
It provides some convenient methods for working with the document like body()
.
Usage
use leptos::*;
use leptos_use::use_document;
#[component]
fn Demo() -> impl IntoView {
let document = use_document();
// Returns `None` on the server but will not panic.
let body = document.body();
view! { }
}
Types
Source
use_document_visibility
Reactively track document.visibilityState
Demo
Usage
use leptos::*;
use leptos_use::use_document_visibility;
#[component]
fn Demo() -> impl IntoView {
let visibility = use_document_visibility();
view! { }
}
Server-Side Rendering
On the server this returns a Signal
that always contains the value web_sys::VisibilityState::Hidden
.
Source
use_draggable
Make elements draggable.
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::{use_draggable_with_options, UseDraggableOptions, UseDraggableReturn};
use leptos_use::core::Position;
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
// `style` is a helper string "left: {x}px; top: {y}px;"
let UseDraggableReturn {
x,
y,
style,
..
} = use_draggable_with_options(
el,
UseDraggableOptions::default().initial_value(Position { x: 40.0, y: 40.0 }),
);
view! {
<div node_ref=el style=move || format!("position: fixed; {}", style.get())>
Drag me! I am at { x }, { y }
</div>
}
}
Types
Source
use_drop_zone
Create a zone where files can be dropped.
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::{use_drop_zone_with_options, UseDropZoneOptions, UseDropZoneReturn};
#[component]
fn Demo() -> impl IntoView {
let drop_zone_el = create_node_ref::<Div>();
let on_drop = |event| {
// called when files are dropped on zone
};
let UseDropZoneReturn {
is_over_drop_zone,
..
} = use_drop_zone_with_options(
drop_zone_el,
UseDropZoneOptions::default().on_drop(on_drop)
);
view! {
<div node_ref=drop_zone_el>
"Drop files here"
</div>
}
}
Server-Side Rendering
On the server the returned file
signal always contains an empty Vec
and
is_over_drop_zone
contains always false
Types
Source
use_element_bounding
Reactive bounding box of an HTML element
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::{use_element_bounding, UseElementBoundingReturn};
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let UseElementBoundingReturn {
x, y, top,right,bottom,left, width, height, ..
} = use_element_bounding(el);
view! { <div node_ref=el></div> }
}
Server-Side Rendering
On the server the returned signals always are 0.0
and update
is a no-op.
Types
Source
use_element_size
Reactive size of an HTML element.
Please refer to ResizeObserver on MDN for more details.
Demo
Usage
use leptos::{html::Div, *};
use leptos_use::{use_element_size, UseElementSizeReturn};
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let UseElementSizeReturn { width, height } = use_element_size(el);
view! {
<div node_ref=el>
"Width: " {width}
"Height: " {height}
</div>
}
}
Server-Side Rendering
On the server the returned signals always contain the value of the initial_size
option.
See also
Types
Source
use_element_visibility
Tracks the visibility of an element within the viewport.
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::use_element_visibility;
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let is_visible = use_element_visibility(el);
view! {
<div node_ref=el>
<h1>{is_visible}</h1>
</div>
}
}
Server-Side Rendering
On the server this returns a Signal
that always contains the value false
.
See also
Types
Source
use_intersection_observer
Reactive IntersectionObserver.
Detects that a target element's visibility inside the viewport.
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::use_intersection_observer;
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let (is_visible, set_visible) = create_signal(false);
use_intersection_observer(
el,
move |entries, _| {
set_visible.set(entries[0].is_intersecting());
},
);
view! {
<div node_ref=el>
<h1>"Hello World"</h1>
</div>
}
}
Server-Side Rendering
On the server this amounts to a no-op.
See also
Types
Source
use_mouse_in_element
Reactive mouse position related to an element.
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::{use_mouse_in_element, UseMouseInElementReturn};
#[component]
fn Demo() -> impl IntoView {
let target = create_node_ref::<Div>();
let UseMouseInElementReturn { x, y, is_outside, .. } = use_mouse_in_element(target);
view! {
<div node_ref=target>
<h1>Hello world</h1>
</div>
}
}
Server-Side Rendering
On the server this returns simple Signals with the initial_value
for x
and y
,
no-op for stop
, is_outside = true
and 0.0
for the rest of the signals.
Types
Source
use_mutation_observer
Reactive MutationObserver.
Watch for changes being made to the DOM tree.
Demo
Usage
use leptos::*;
use leptos::html::Pre;
use leptos_use::{use_mutation_observer_with_options, UseMutationObserverOptions};
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Pre>();
let (text, set_text) = create_signal("".to_string());
use_mutation_observer_with_options(
el,
move |mutations, _| {
if let Some(mutation) = mutations.first() {
set_text.update(|text| *text = format!("{text}\n{:?}", mutation.attribute_name()));
}
},
UseMutationObserverOptions::default().attributes(true),
);
view! {
<pre node_ref=el>{ text }</pre>
}
}
Server-Side Rendering
On the server this amounts to a no-op.
Types
Source
use_resize_observer
Reports changes to the dimensions of an Element's content or the border-box.
Please refer to ResizeObserver on MDN for more details.
Demo
Usage
use leptos::{html::Div, *};
use leptos_use::use_resize_observer;
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let (text, set_text) = create_signal("".to_string());
use_resize_observer(
el,
move |entries, observer| {
let rect = entries[0].content_rect();
set_text.set(format!("width: {}\nheight: {}", rect.width(), rect.height()));
},
);
view! {
<div node_ref=el>{ move || text.get() }</div>
}
}
Server-Side Rendering
On the server this amounts to a no-op.
See also
Types
Source
use_window
SSR safe window()
.
This returns just a new-type wrapper around Option<Window>
.
Calling this amounts to None
on the server and Some(Window)
on the client.
It provides some convenient methods for working with the window like document()
and navigator()
.
These will all return None
on the server.
Usage
use leptos::*;
use leptos_use::use_window;
#[component]
fn Demo() -> impl IntoView {
let window = use_window();
// Returns `None` on the server but will not panic.
let navigator = window.navigator();
view! { }
}
Types
Source
use_window_focus
Reactively track window focus
with window.onfocus
and window.onblur
events.
Demo
Usage
use leptos::*;
use leptos_use::use_window_focus;
#[component]
fn Demo() -> impl IntoView {
let focused = use_window_focus();
view! { }
}
Server-Side Rendering
On the server this returns a Signal
that is always true
.
Source
use_window_scroll
Reactive window scroll.
Demo
Usage
use leptos::*;
use leptos_use::use_window_scroll;
#[component]
fn Demo() -> impl IntoView {
let (x, y) = use_window_scroll();
view! { }
}
Server-Side Rendering
On the server this returns Signal
s that are always 0.0
.
Source
use_breakpoints
Reactive viewport breakpoints.
Demo
Usage
use leptos::*;
use leptos_use::{use_breakpoints, BreakpointsTailwind, breakpoints_tailwind};
#[component]
fn Demo() -> impl IntoView {
let screen_width = use_breakpoints(breakpoints_tailwind());
use BreakpointsTailwind::*;
let sm_and_larger = screen_width.ge(Sm);
let larger_than_sm = screen_width.gt(Sm);
let lg_and_smaller = screen_width.le(Lg);
let smaller_than_lg = screen_width.lt(Lg);
view! { }
}
Breakpoints
There are many predefined breakpoints for major UI frameworks. The following are provided.
breakpoints_tailwind
breakpoints_bootstrap_v5
breakpoints_material
breakpoints_ant_design
breakpoints_quasar
breakpoints_semantic
breakpoints_master_css
You can also provide your own breakpoints.
use std::collections::HashMap;
use leptos::*;
use leptos_use::use_breakpoints;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum MyBreakpoints {
Tablet,
Laptop,
Desktop,
}
fn my_breakpoints() -> HashMap<MyBreakpoints, u32> {
use MyBreakpoints::*;
HashMap::from([
(Tablet, 640),
(Laptop, 1024),
(Desktop, 1280),
])
}
#[component]
fn Demo() -> impl IntoView {
let screen_width = use_breakpoints(my_breakpoints());
use MyBreakpoints::*;
let laptop = screen_width.between(Laptop, Desktop);
view! { }
}
Non-reactive methods
For every reactive method there is also a non-reactive variant that is prefixed with is_
use leptos::*;
use leptos_use::{use_breakpoints, BreakpointsTailwind, breakpoints_tailwind};
#[component]
fn Demo() -> impl IntoView {
let screen_width = use_breakpoints(breakpoints_tailwind());
use BreakpointsTailwind::*;
let sm_and_larger = screen_width.is_ge(Sm);
let larger_than_sm = screen_width.is_gt(Sm);
let lg_and_smaller = screen_width.is_le(Lg);
let smaller_than_lg = screen_width.is_lt(Lg);
view! { }
}
Server-Side Rendering
Since internally this uses use_media_query
, which returns always false
on the server,
the returned methods also will return false
.
Types
struct UseBreakpointsReturn
enum BreakpointsTailwind
enum BreakpointsBootstrapV5
enum BreakpointsMaterial
enum BreakpointsAntDesign
enum BreakpointsQuasar
enum BreakpointsSematic
enum BreakpointsMasterCss
Source
use_broadcast_channel
Reactive BroadcastChannel API.
Closes a broadcast channel automatically when the component is cleaned up.
Demo
Usage
The BroadcastChannel interface represents a named channel that any browsing context of a given origin can subscribe to. It allows communication between different documents (in different windows, tabs, frames, or iframes) of the same origin.
Messages are broadcasted via a message event fired at all BroadcastChannel objects listening to the channel.
use leptos::*;
use leptos_use::{use_broadcast_channel, UseBroadcastChannelReturn};
use leptos_use::utils::FromToStringCodec;
#[component]
fn Demo() -> impl IntoView {
let UseBroadcastChannelReturn {
is_supported,
message,
post,
error,
close,
..
} = use_broadcast_channel::<bool, FromToStringCodec>("some-channel-name");
post(&true);
close();
view! { }
}
Just like with use_storage
you can use different codecs for encoding and decoding.
use leptos::*;
use serde::{Deserialize, Serialize};
use leptos_use::use_broadcast_channel;
use leptos_use::utils::JsonCodec;
// Data sent in JSON must implement Serialize, Deserialize:
#[derive(Serialize, Deserialize, Clone, PartialEq)]
pub struct MyState {
pub playing_lego: bool,
pub everything_is_awesome: String,
}
#[component]
fn Demo() -> impl IntoView {
use_broadcast_channel::<MyState, JsonCodec>("everyting-is-awesome");
view! { }
}
Create Your Own Custom Codec
All you need to do is to implement the StringCodec
trait together with Default
and Clone
.
Types
Source
use_clipboard
Reactive Clipboard API. Provides the ability to respond to clipboard commands (cut, copy, and paste) as well as to asynchronously read from and write to the system clipboard. Access to the contents of the clipboard is gated behind the Permissions API. Without user permission, reading or altering the clipboard contents is not permitted.
This function requires
--cfg=web_sys_unstable_apis
to be activated as described in the wasm-bindgen guide.
Demo
Usage
use leptos::*;
use leptos_use::{use_clipboard, UseClipboardReturn};
#[component]
fn Demo() -> impl IntoView {
let UseClipboardReturn { is_supported, text, copied, copy } = use_clipboard();
view! {
<Show
when=is_supported
fallback=move || view! { <p>Your browser does not support Clipboard API</p> }
>
<button on:click={
let copy = copy.clone();
move |_| copy("Hello!")
}>
<Show when=copied fallback=move || "Copy">
"Copied!"
</Show>
</button>
</Show>
}
}
Server-Side Rendering
On the server the returnd text
signal will always be None
and copy
is a no-op.
Types
Source
use_color_mode
Reactive color mode (dark / light / customs) with auto data persistence.
Demo
Usage
use leptos::*;
use leptos_use::{use_color_mode, UseColorModeReturn};
#[component]
fn Demo() -> impl IntoView {
let UseColorModeReturn {
mode, // Signal<ColorMode::dark | ColorMode::light>
set_mode,
..
} = use_color_mode();
view! { }
}
By default, it will match with users' browser preference using use_preferred_dark
(a.k.a. ColorMode::Auto
).
When reading the signal, it will by default return the current color mode (ColorMode::Dark
, ColorMode::Light
or
your custom modes ColorMode::Custom("some-custom")
). The ColorMode::Auto
variant can
be included in the returned modes by enabling the emit_auto
option and using use_color_mode_with_options
.
When writing to the signal (set_mode
), it will trigger DOM updates and persist the color mode to local
storage (or your custom storage). You can pass ColorMode::Auto
to set back to auto mode.
use leptos::*;
use leptos_use::{ColorMode, use_color_mode, UseColorModeReturn};
#[component]
fn Demo() -> impl IntoView {
let UseColorModeReturn { mode, set_mode, .. } = use_color_mode();
mode.get(); // ColorMode::Dark or ColorMode::Light
set_mode.set(ColorMode::Dark); // change to dark mode and persist
set_mode.set(ColorMode::Auto); // change to auto mode
view! { }
}
Options
use leptos::*;
use leptos_use::{use_color_mode_with_options, UseColorModeOptions, UseColorModeReturn};
#[component]
fn Demo() -> impl IntoView {
let UseColorModeReturn { mode, set_mode, .. } = use_color_mode_with_options(
UseColorModeOptions::default()
.attribute("theme") // instead of writing to `class`
.custom_modes(vec![
// custom colors in addition to light/dark
"dim".to_string(),
"cafe".to_string(),
]),
); // Signal<ColorMode::Dark | ColorMode::Light | ColorMode::Custom("dim") | ColorMode::Custom("cafe")>
view! { }
}
Cookies
To persist color mode in a cookie, use use_cookie_with_options
and specify .cookie_enabled(true)
.
Note: To work with SSR you have to add the
axum
oractix
feature as described inuse_cookie
.
use leptos::*;
use leptos_meta::*;
use leptos_use::{use_color_mode_with_options, UseColorModeOptions, UseColorModeReturn};
#[component]
fn Demo() -> impl IntoView {
let UseColorModeReturn { mode, set_mode, .. } = use_color_mode_with_options(
UseColorModeOptions::default()
.cookie_enabled(true),
);
// This adds the color mode class to the `<html>` element even with SSR
view! {
<Html class=move || mode.get().to_string()/>
}
}
For a working example please check out the ssr example.
Server-Side Rendering
On the server this will by default return ColorMode::Light
. Persistence with storage is disabled.
If cookie_enabled
is set to true
, cookies will be used and if present this value will be used
on the server as well as on the client. Please note that you have to add the axum
or actix
feature as described in use_cookie
.
See also
Types
Source
use_cookie
SSR-friendly and reactive cookie access.
You can use this function multiple times in your for the same cookie and they're signals will synchronize
(even across windows/tabs). But there is no way to listen to changes to document.cookie
directly so in case
something outside of this function changes the cookie, the signal will not be updated.
When the options max_age
or expire
is given then the returned signal will
automatically turn to None
after that time.
Demo
Usage
The example below creates a cookie called counter
. If the cookie doesn't exist, it is initially set to a random value.
Whenever we update the counter
variable, the cookie will be updated accordingly.
use leptos::*;
use leptos_use::use_cookie;
use leptos_use::utils::FromToStringCodec;
use rand::prelude::*;
#[component]
fn Demo() -> impl IntoView {
let (counter, set_counter) = use_cookie::<u32, FromToStringCodec>("counter");
let reset = move || set_counter.set(Some(random()));
if counter.get().is_none() {
reset();
}
let increase = move || {
set_counter.set(counter.get().map(|c| c + 1));
};
view! {
<p>Counter: {move || counter.get().map(|c| c.to_string()).unwrap_or("β".to_string())}</p>
<button on:click=move |_| reset()>Reset</button>
<button on:click=move |_| increase()>+</button>
}
}
See StringCodec
for details on how to handle versioning β dealing with data that can outlast your code.
Cookie attributes
As part of the options when you use use_cookie_with_options
you can specify cookie attributes.
use cookie::SameSite;
use leptos::*;
use leptos_use::{use_cookie_with_options, UseCookieOptions};
use leptos_use::utils::FromToStringCodec;
#[component]
fn Demo() -> impl IntoView {
let (cookie, set_cookie) = use_cookie_with_options::<bool, FromToStringCodec>(
"user_info",
UseCookieOptions::default()
.max_age(3600_000) // one hour
.same_site(SameSite::Lax)
);
view! {}
}
Server-Side Rendering
This works equally well on the server or the client.
On the server this function reads the cookie from the HTTP request header and writes it back into
the HTTP response header according to options (if provided).
The returned WriteSignal
will not affect the cookie headers on the server.
If you're using
axum
you have to enable the"axum"
feature in your Cargo.toml. In case it'sactix-web
enable the feature"actix"
, forspin
enable"spin"
.
Bring your own header
In case you're neither using Axum nor Actix, or the default implementation is not to your liking, you can provide your own way of reading and writing the cookie header value.
use cookie::Cookie;
use leptos::*;
use serde::{Deserialize, Serialize};
use leptos_use::{use_cookie_with_options, UseCookieOptions};
use leptos_use::utils::JsonCodec;
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
pub struct Auth {
pub username: String,
pub token: String,
}
#[component]
fn Demo() -> impl IntoView {
use_cookie_with_options::<Auth, JsonCodec>(
"auth",
UseCookieOptions::default()
.ssr_cookies_header_getter(|| {
#[cfg(feature = "ssr")]
{
Some("Somehow get the value of the cookie header as a string".to_owned())
}
})
.ssr_set_cookie(|cookie: &Cookie| {
#[cfg(feature = "ssr")]
{
// somehow insert the Set-Cookie header for this cookie
}
}),
);
view! {}
}
Create Your Own Custom Codec
All you need to do is to implement the StringCodec
trait together with Default
and Clone
.
Types
Source
use_css_var
Manipulate CSS variables.
Demo
Usage
use leptos::*;
use leptos_use::use_css_var;
#[component]
fn Demo() -> impl IntoView {
let (color, set_color) = use_css_var("--color");
set_color.set("red".to_string());
view! { }
}
The variable name itself can be a Signal
.
use leptos::*;
use leptos_use::use_css_var;
#[component]
fn Demo() -> impl IntoView {
let (key, set_key) = create_signal("--color".to_string());
let (color, set_color) = use_css_var(key);
view! { }
}
You can specify the element that the variable is applied to as well as an initial value in case the variable is not set yet. The option to listen for changes to the variable is also available.
use leptos::*;
use leptos::html::Div;
use leptos_use::{use_css_var_with_options, UseCssVarOptions};
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let (color, set_color) = use_css_var_with_options(
"--color",
UseCssVarOptions::default()
.target(el)
.initial_value("#eee")
.observe(true),
);
view! {
<div node_ref=el>"..."</div>
}
}
Server-Side Rendering
On the server this simply returns create_signal(options.initial_value)
.
Types
Source
use_display_media
Reactive mediaDevices.getDisplayMedia
streaming.
Demo
Usage
use leptos::*;
use leptos_use::{use_display_media, UseDisplayMediaReturn};
#[component]
fn Demo() -> impl IntoView {
let video_ref = create_node_ref::<leptos::html::Video>();
let UseDisplayMediaReturn { stream, start, .. } = use_display_media();
start();
create_effect(move |_|
video_ref.get().map(|v| {
match stream.get() {
Some(Ok(s)) => v.set_src_object(Some(&s)),
Some(Err(e)) => logging::error!("Failed to get media stream: {:?}", e),
None => logging::log!("No stream yet"),
}
})
);
view! { <video node_ref=video_ref controls=false autoplay=true muted=true></video> }
}
Server-Side Rendering
On the server calls to start
or any other way to enable the stream will be ignored
and the stream will always be None
.
Types
Source
use_event_listener
Use EventListener with ease. Register using addEventListener on mounted, and removeEventListener automatically on cleanup.
Usage
use leptos::*;
use leptos::ev::visibilitychange;
use leptos::logging::log;
use leptos_use::{use_document, use_event_listener};
#[component]
fn Demo() -> impl IntoView {
use_event_listener(use_document(), visibilitychange, |evt| {
log!("{:?}", evt);
});
view! { }
}
You can also pass a NodeRef
as the event target, use_event_listener
will unregister the previous event and register
the new one when you change the target.
use leptos::*;
use leptos::ev::click;
use leptos::logging::log;
use leptos_use::use_event_listener;
#[component]
fn Demo() -> impl IntoView {
let element = create_node_ref();
use_event_listener(element, click, |evt| {
log!("click from element {:?}", event_target::<web_sys::HtmlDivElement>(&evt));
});
let (cond, set_cond) = create_signal(true);
view! {
<Show
when=move || cond.get()
fallback=move || view! { <div node_ref=element>"Condition false"</div> }
>
<div node_ref=element>"Condition true"</div>
</Show>
}
}
You can also call the returned to unregister the listener.
use leptos::*;
use leptos::ev::keydown;
use leptos::logging::log;
use web_sys::KeyboardEvent;
use leptos_use::use_event_listener;
#[component]
fn Demo() -> impl IntoView {
let cleanup = use_event_listener(document().body(), keydown, |evt: KeyboardEvent| {
log!("{}", &evt.key());
});
cleanup();
view! { }
}
Server-Side Rendering
On the server this amounts to a noop.
Types
Source
use_favicon
Reactive favicon.
Demo
Usage
use leptos::*;
use leptos_use::use_favicon;
#[component]
fn Demo() -> impl IntoView {
let (icon, set_icon) = use_favicon();
set_icon.set(Some("dark.png".to_string())); // change current icon
view! { }
}
Passing a Source Signal
You can pass a Signal
to use_favicon_with_options
. Change from the source signal will be
reflected in your favicon automatically.
use leptos::*;
use leptos_use::{use_favicon_with_options, UseFaviconOptions, use_preferred_dark};
#[component]
fn Demo() -> impl IntoView {
let is_dark = use_preferred_dark();
let (icon, _) = use_favicon_with_options(
UseFaviconOptions::default().new_icon(
Signal::derive(move || {
Some((if is_dark.get() { "dark.png" } else { "light.png" }).to_string())
}),
)
);
view! { }
}
Server-Side Rendering
On the server only the signals work but no favicon will be changed obviously.
Types
Source
use_media_query
Reactive Media Query.
Demo
Usage
use leptos::*;
use leptos_use::use_media_query;
#[component]
fn Demo() -> impl IntoView {
let is_large_screen = use_media_query("(min-width: 1024px)");
let is_dark_preferred = use_media_query("(prefers-color-scheme: dark)");
view! { }
}
Server-Side Rendering
On the server this functions returns a Signal that is always false
.
See also
Source
use_permission
Reactive Permissions API.
Demo
Usage
use leptos::*;
use leptos_use::use_permission;
#[component]
fn Demo() -> impl IntoView {
let microphone_access = use_permission("microphone");
view! { }
}
Server-Side Rendering
On the server the returned signal will always be PermissionState::Unknown
.
Types
Source
use_preferred_contrast
Reactive prefers-contrast media query.
Usage
use leptos::*;
use leptos_use::use_preferred_contrast;
#[component]
fn Demo() -> impl IntoView {
let preferred_contrast = use_preferred_contrast();
view! { }
}
Server-Side Rendering
On the server this returns a Signal
that always contains the value PreferredContrast::NoPreference
.
See also
Types
Source
use_preferred_dark
Reactive dark theme preference.
Usage
use leptos::*;
use leptos_use::use_preferred_dark;
#[component]
fn Demo() -> impl IntoView {
let is_dark_preferred = use_preferred_dark();
view! { }
}
Server-Side Rendering
On the server this functions returns a Signal that is always false
.
See also
Source
use_service_worker
Reactive ServiceWorker API.
Please check the working example.
Usage
use leptos::*;
use leptos_use::{use_service_worker_with_options, UseServiceWorkerOptions, UseServiceWorkerReturn};
#[component]
fn Demo() -> impl IntoView {
let UseServiceWorkerReturn {
registration,
installing,
waiting,
active,
skip_waiting,
check_for_update,
} = use_service_worker_with_options(UseServiceWorkerOptions::default()
.script_url("service-worker.js")
.skip_waiting_message("skipWaiting"),
);
view! { }
}
Server-Side Rendering
This function does not support SSR. Call it inside a create_effect
.
Types
Source
use_web_notification
Reactive Notification API.
The Web Notification interface of the Notifications API is used to configure and display desktop notifications to the user.
Demo
Usage
use leptos::*;
use leptos_use::{use_web_notification_with_options, UseWebNotificationOptions, ShowOptions, UseWebNotificationReturn, NotificationDirection};
#[component]
fn Demo() -> impl IntoView {
let UseWebNotificationReturn {
show,
close,
..
} = use_web_notification_with_options(
UseWebNotificationOptions::default()
.direction(NotificationDirection::Auto)
.language("en")
.tag("test"),
);
show(ShowOptions::default().title("Hello World from leptos-use"));
view! { }
}
Server-Side Rendering
This function is basically ignored on the server. You can safely call show
but it will do nothing.
Types
enum NotificationDirection
struct UseWebNotificationOptions
struct ShowOptions
enum NotificationPermission
struct UseWebNotificationReturn
Source
on_click_outside
Listen for clicks outside of an element. Useful for modals or dropdowns.
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos::html::Div;
use leptos_use::on_click_outside;
#[component]
fn Demo() -> impl IntoView {
let target = create_node_ref::<Div>();
on_click_outside(target, move |event| { log!("{:?}", event); });
view! {
<div node_ref=target>"Hello World"</div>
<div>"Outside element"</div>
}
}
This function uses Event.composedPath() which is not supported by IE 11, Edge 18 and below. If you are targeting these browsers, we recommend you to include this code snippet on your project.
Excluding Elements
Use this to ignore clicks on certain elements.
use leptos::*;
use leptos::logging::log;
use leptos::html::Div;
use leptos_use::{on_click_outside_with_options, OnClickOutsideOptions};
#[component]
fn Demo() -> impl IntoView {
let target = create_node_ref::<Div>();
on_click_outside_with_options(
target,
move |event| { log!("{:?}", event); },
OnClickOutsideOptions::default().ignore(["input", "#some-id"]),
);
view! {
<div node_ref=target>"Hello World"</div>
}
}
Server-Side Rendering
On the server this amounts to a no-op.
Types
Source
use_device_orientation
Reactive DeviceOrientationEvent. Provide web developers with information from the physical orientation of the device running the web page.
Demo
Usage
use leptos::*;
use leptos_use::{use_device_orientation, UseDeviceOrientationReturn};
#[component]
fn Demo() -> impl IntoView {
let UseDeviceOrientationReturn {
is_supported,
absolute,
alpha,
beta,
gamma,
} = use_device_orientation();
view! { }
}
Server-Side Rendering
On the server this function returns values as if the orientation capabilties were not supported by the device.
Types
Source
use_device_pixel_ratio
Reactive window.devicePixelRatio
NOTE: there is no event listener for
window.devicePixelRatio
change. So this function uses the same mechanism as described in this example.
Demo
Usage
use leptos::*;
use leptos_use::use_device_pixel_ratio;
#[component]
fn Demo() -> impl IntoView {
let pixel_ratio = use_device_pixel_ratio();
view! { }
}
Server-Side Rendering
On the server this function returns a Signal that is always 1.0
.
Source
use_element_hover
Reactive element's hover state.
Demo
Usage
use leptos::*;
use leptos::html::Button;
use leptos_use::use_element_hover;
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Button>();
let is_hovered = use_element_hover(el);
view! {
<button node_ref=el>{ move || format!("{:?}", is_hovered.get()) }</button>
}
}
Server-Side Rendering
On the server this returns a Signal
that always contains the value false
.
Types
Source
use_geolocation
Reactive Geolocation API. It allows the user to provide their location to web applications if they so desire. For privacy reasons, the user is asked for permission to report location information.
Demo
Usage
use leptos::*;
use leptos_use::{use_geolocation, UseGeolocationReturn};
#[component]
fn Demo() -> impl IntoView {
let UseGeolocationReturn {
coords,
located_at,
error,
resume,
pause,
} = use_geolocation();
view! { }
}
Server-Side Rendering
On the server all signals returns will always contain None
and the functions do nothing.
Types
Source
use_idle
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::{use_idle, UseIdleReturn};
#[component]
fn Demo() -> impl IntoView {
let UseIdleReturn {
idle, last_active, ..
} = use_idle(5 * 60 * 1000); // 5 minutes
log!("{}", idle.get()); // true or false
view! { }
}
Programatically resetting:
use std::time::Duration;
use leptos::*;
use leptos::logging::log;
use leptos_use::{use_idle, UseIdleReturn};
#[component]
fn Demo() -> impl IntoView {
let UseIdleReturn {
idle, last_active, reset
} = use_idle(5 * 60 * 1000); // 5 minutes
reset(); // restarts the idle timer. Does not change the `last_active` value.
view! { }
}
Server-Side Rendering
On the server this will always return static signals
UseIdleReturn{
idle: Signal(initial_state),
last_active: Signal(now),
reset: || {}
}
Types
Source
use_infinite_scroll
Infinite scrolling of the element.
Demo
Usage
use leptos::*;
use leptos::html::Div;
use leptos_use::{use_infinite_scroll_with_options, UseInfiniteScrollOptions};
#[component]
fn Demo() -> impl IntoView {
let el = create_node_ref::<Div>();
let (data, set_data) = create_signal(vec![1, 2, 3, 4, 5, 6]);
let _ = use_infinite_scroll_with_options(
el,
move |_| async move {
let len = data.with(|d| d.len());
set_data.update(|data| *data = (1..len+6).collect());
},
UseInfiniteScrollOptions::default().distance(10.0),
);
view! {
<div node_ref=el>
<For each=move || data.get() key=|i| *i let:item>{ item }</For>
</div>
}
}
The returned signal is true
while new data is being loaded.
Types
Source
use_mouse
Reactive mouse position
Demo
Basic Usage
use leptos::*;
use leptos_use::{use_mouse, UseMouseReturn};
#[component]
fn Demo() -> impl IntoView {
let UseMouseReturn {
x, y, source_type, ..
} = use_mouse();
view! { }
}
Touch is enabled by default. To only detect mouse changes, set touch
to false
.
The dragover
event is used to track mouse position while dragging.
use leptos::*;
use leptos_use::{use_mouse_with_options, UseMouseOptions, UseMouseReturn};
#[component]
fn Demo() -> impl IntoView {
let UseMouseReturn {
x, y, ..
} = use_mouse_with_options(
UseMouseOptions::default().touch(false)
);
view! { }
}
Custom Extractor
It's also possible to provide a custom extractor to get the position from the events.
use leptos::*;
use leptos::html::Div;
use web_sys::MouseEvent;
use leptos_use::{use_mouse_with_options, UseMouseOptions, UseMouseReturn, UseMouseEventExtractor, UseMouseCoordType};
#[derive(Clone)]
struct MyExtractor;
impl UseMouseEventExtractor for MyExtractor {
fn extract_mouse_coords(&self, event: &MouseEvent) -> Option<(f64, f64)> {
Some((event.offset_x() as f64, event.offset_y() as f64))
}
// don't implement fn extract_touch_coords to ignore touch events
}
#[component]
fn Demo() -> impl IntoView {
let element = create_node_ref::<Div>();
let UseMouseReturn {
x, y, source_type, ..
} = use_mouse_with_options(
UseMouseOptions::default()
.target(element)
.coord_type(UseMouseCoordType::Custom(MyExtractor))
);
view! { <div node_ref=element></div> }
}
Server-Side Rendering
On the server this returns simple Signal
s with the initial_value
s.
Types
struct UseMouseOptions
enum UseMouseCoordType
struct UseMouseEventExtractorDefault
struct UseMouseReturn
enum UseMouseSourceType
Source
use_scroll
We have to check if the scroll amount is close enough to some threshold in order to more accurately calculate arrivedState. This is because scrollTop/scrollLeft are non-rounded numbers, while scrollHeight/scrollWidth and clientHeight/clientWidth are rounded. https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollHeight#determine_if_an_element_has_been_totally_scrolled
Types
Source
use_event_source
Reactive EventSource
An EventSource or Server-Sent-Events instance opens a persistent connection to an HTTP server, which sends events in text/event-stream format.
Usage
Values are decoded via the given Codec
.
To use the
JsonCodec
, you will need to add the"serde"
feature to your project'sCargo.toml
. To useProstCodec
, add the feature"prost"
.
use leptos::*;
use leptos_use::{use_event_source, UseEventSourceReturn, utils::JsonCodec};
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Clone, PartialEq)]
pub struct EventSourceData {
pub message: String,
pub priority: u8,
}
#[component]
fn Demo() -> impl IntoView {
let UseEventSourceReturn {
ready_state, data, error, close, ..
} = use_event_source::<EventSourceData, JsonCodec>("https://event-source-url");
view! { }
}
Create Your Own Custom Codec
All you need to do is to implement the StringCodec
trait together with Default
and Clone
.
Named Events
You can define named events when using use_event_source_with_options
.
use leptos::*;
use leptos_use::{use_event_source_with_options, UseEventSourceReturn, UseEventSourceOptions, utils::FromToStringCodec};
#[component]
fn Demo() -> impl IntoView {
let UseEventSourceReturn {
ready_state, data, error, close, ..
} = use_event_source_with_options::<String, FromToStringCodec>(
"https://event-source-url",
UseEventSourceOptions::default()
.named_events(["notice".to_string(), "update".to_string()])
);
view! { }
}
Immediate
Auto-connect (enabled by default).
This will call open()
automatically for you, and you don't need to call it by yourself.
Auto-Reconnection
Reconnect on errors automatically (enabled by default).
You can control the number of reconnection attempts by setting reconnect_limit
and the
interval between them by setting reconnect_interval
.
use leptos::*;
use leptos_use::{use_event_source_with_options, UseEventSourceReturn, UseEventSourceOptions, utils::FromToStringCodec};
#[component]
fn Demo() -> impl IntoView {
let UseEventSourceReturn {
ready_state, data, error, close, ..
} = use_event_source_with_options::<bool, FromToStringCodec>(
"https://event-source-url",
UseEventSourceOptions::default()
.reconnect_limit(5) // at most 5 attempts
.reconnect_interval(2000) // wait for 2 seconds between attempts
);
view! { }
}
To disable auto-reconnection, set reconnect_limit
to 0
.
Server-Side Rendering
On the server-side, use_event_source
will always return ready_state
as ConnectionReadyState::Closed
,
data
, event
and error
will always be None
, and open
and close
will do nothing.
Types
Source
use_websocket
Creating and managing a Websocket connection.
Demo
Usage
use leptos::*;
use leptos_use::{use_websocket, UseWebsocketReturn};
use leptos_use::core::ConnectionReadyState;
#[component]
fn Demo() -> impl IntoView {
let UseWebsocketReturn {
ready_state,
message,
message_bytes,
send,
send_bytes,
open,
close,
..
} = use_websocket("wss://echo.websocket.events/");
let send_message = move |_| {
send("Hello, world!");
};
let send_byte_message = move |_| {
send_bytes(b"Hello, world!\r\n".to_vec());
};
let status = move || ready_state.get().to_string();
let connected = move || ready_state.get() == ConnectionReadyState::Open;
let open_connection = move |_| {
open();
};
let close_connection = move |_| {
close();
};
view! {
<div>
<p>"status: " {status}</p>
<button on:click=send_message disabled=move || !connected()>"Send"</button>
<button on:click=send_byte_message disabled=move || !connected()>"Send bytes"</button>
<button on:click=open_connection disabled=connected>"Open"</button>
<button on:click=close_connection disabled=move || !connected()>"Close"</button>
<p>"Receive message: " {move || format!("{:?}", message.get())}</p>
<p>"Receive byte message: " {move || format!("{:?}", message_bytes.get())}</p>
</div>
}
}
Relative Paths
If the provided url
is relative, it will be resolved relative to the current page.
Urls will be resolved like this the following. Please note that the protocol (http vs https) will
be taken into account as well.
Current Page | Relative Url | Resolved Url |
---|---|---|
http://example.com/some/where | /api/ws | ws://example.com/api/ws |
https://example.com/some/where | /api/ws | wss://example.com/api/ws |
https://example.com/some/where | api/ws | wss://example.com/some/where/api/ws |
https://example.com/some/where | //otherdomain.com/api/ws | wss://otherdomain.com/api/ws |
Usage with provide_context
The return value of use_websocket
utilizes several type parameters which can make it
cumbersome to use with provide_context
+ expect_context
.
The following example shows how to avoid type parameters with dynamic dispatch.
This sacrifices a little bit of performance for the sake of ergonomics. However,
compared to network transmission speeds this loss of performance is negligible.
First we define the struct
that is going to be passed around as context.
use leptos::*;
use std::rc::Rc;
#[derive(Clone)]
pub struct WebsocketContext {
pub message: Signal<Option<String>>,
send: Rc<dyn Fn(&str)>, // use Rc to make it easily cloneable
}
impl WebsocketContext {
pub fn new(message: Signal<Option<String>>, send: Rc<dyn Fn(&str)>) -> Self {
Self {
message,
send,
}
}
// create a method to avoid having to use parantheses around the field
#[inline(always)]
pub fn send(&self, message: &str) {
(self.send)(message)
}
}
Now you can provide the context like the following.
use leptos::*;
use leptos_use::{use_websocket, UseWebsocketReturn};
use std::rc::Rc;
#[derive(Clone)]
pub struct WebsocketContext {
pub message: Signal<Option<String>>,
send: Rc<dyn Fn(&str)>,
}
impl WebsocketContext {
pub fn new(message: Signal<Option<String>>, send: Rc<dyn Fn(&str)>) -> Self {
Self {
message,
send,
}
}
}
#[component]
fn Demo() -> impl IntoView {
let UseWebsocketReturn {
message,
send,
..
} = use_websocket("ws:://some.websocket.io");
provide_context(WebsocketContext::new(message, Rc::new(send.clone())));
view! {}
}
Finally let's use the context:
use leptos::*;
use leptos_use::{use_websocket, UseWebsocketReturn};
use std::rc::Rc;
#[derive(Clone)]
pub struct WebsocketContext {
pub message: Signal<Option<String>>,
send: Rc<dyn Fn(&str)>,
}
impl WebsocketContext {
#[inline(always)]
pub fn send(&self, message: &str) {
(self.send)(message)
}
}
#[component]
fn Demo() -> impl IntoView {
let websocket = expect_context::<WebsocketContext>();
websocket.send("Hello World!");
view! {}
}
Server-Side Rendering
On the server the returned functions amount to no-ops.
Types
Source
use_interval
Reactive counter increases on every interval.
Demo
Usage
use leptos::*;
use leptos_use::{use_interval, UseIntervalReturn};
#[component]
fn Demo() -> impl IntoView {
let UseIntervalReturn {
counter,
reset,
is_active,
pause,
resume
} = use_interval( 200 );
view! { }
}
Server-Side Rendering
On the server this function will simply be ignored.
Types
Source
use_interval_fn
Wrapper for set_interval
with controls.
Demo
Usage
use leptos::*;
use leptos_use::use_interval_fn;
use leptos_use::utils::Pausable;
#[component]
fn Demo() -> impl IntoView {
let Pausable { pause, resume, is_active } = use_interval_fn(
|| {
// do something
},
1000,
);
view! { }
}
Server-Side Rendering
On the server this function will simply be ignored.
Types
Source
use_raf_fn
Call function on every requestAnimationFrame. With controls of pausing and resuming.
Demo
Usage
use leptos::*;
use leptos_use::use_raf_fn;
use leptos_use::utils::Pausable;
#[component]
fn Demo() -> impl IntoView {
let (count, set_count) = create_signal(0);
let Pausable { pause, resume, is_active } = use_raf_fn(move |_| {
set_count.update(|count| *count += 1);
});
view! { <div>Count: { count }</div> }
}
You can use use_raf_fn_with_options
and set immediate
to false
. In that case
you have to call resume()
before the callback
is executed.
Server-Side Rendering
On the server this does basically nothing. The provided closure will never be called.
Types
Source
use_timeout_fn
Wrapper for setTimeout
with controls.
Demo
Usage
use leptos::*;
use leptos_use::{use_timeout_fn, UseTimeoutFnReturn};
#[component]
fn Demo() -> impl IntoView {
let UseTimeoutFnReturn { start, stop, is_pending, .. } = use_timeout_fn(
|i: i32| {
// do sth
},
3000.0
);
start(3);
view! { }
}
Types
Source
use_timestamp
Reactive current timestamp.
Demo
Usage
use leptos::*;
use leptos_use::use_timestamp;
#[component]
fn Demo() -> impl IntoView {
let timestamp = use_timestamp();
view! { }
}
With controls:
use leptos::*;
use leptos_use::{use_timestamp_with_controls, UseTimestampReturn};
#[component]
fn Demo() -> impl IntoView {
let UseTimestampReturn {
timestamp,
is_active,
pause,
resume,
} = use_timestamp_with_controls();
view! { }
}
Server-Side Rendering
On the server this function will return a signal with the milliseconds since the Unix epoch.
But the signal will never update (as there's no request_animation_frame
on the server).
Types
Source
watch_debounced
A debounced version of watch
.
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::watch_debounced;
pub fn Demo() -> impl IntoView {
let (source, set_source) = create_signal(0);
watch_debounced(
move || source.get(),
move |_, _, _| {
log!("changed!");
},
500.0,
);
view! { }
}
This really is only shorthand shorthand for watch_with_options(deps, callback, WatchOptions::default().debounce(ms))
.
Please note that if the current component is cleaned up before the debounced callback is called, the debounced callback will not be called.
There's also watch_debounced_with_options
where you can specify the other watch options (except filter
).
use leptos::*;
use leptos::logging::log;
use leptos_use::{watch_debounced_with_options, WatchDebouncedOptions};
pub fn Demo() -> impl IntoView {
let (source, set_source) = create_signal(0);
watch_debounced_with_options(
move || source.get(),
move |_, _, _| {
log!("changed!");
},
500.0,
WatchDebouncedOptions::default().max_wait(Some(1000.0)),
);
view! { }
}
Recommended Reading
Server-Side Rendering
On the server the callback
will never be called except if you set immediate
to true
in which case the callback will be
called exactly once.
See also
Types
Source
watch_pausable
Pausable watch
.
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::{watch_pausable, WatchPausableReturn};
pub fn Demo() -> impl IntoView {
let (source, set_source) = create_signal("foo".to_string());
let WatchPausableReturn {
stop,
pause,
resume,
..
} = watch_pausable(
move || source.get(),
|v, _, _| {
log!("Changed to {}", v);
},
);
set_source.set("bar".to_string()); // > "Changed to bar"
pause();
set_source.set("foobar".to_string()); // (nothing happens)
resume();
set_source.set("hello".to_string()); // > "Changed to hello"
view! { }
}
There's also watch_pausable_with_options
which takes the same options as watch
.
Server-Side Rendering
On the server this works just fine except if you throttle or debounce in which case the callback
will never be called except if you set immediate
to true
in which case the callback will be
called exactly once.
See also
Types
Source
watch_throttled
A throttled version of watch
.
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::watch_throttled;
pub fn Demo() -> impl IntoView {
let (source, set_source) = create_signal(0);
watch_throttled(
move || source.get(),
move |_, _, _| {
log!("changed!");
},
500.0,
);
view! { }
}
This really is only shorthand shorthand for watch_with_options(deps, callback, WatchOptions::default().throttle(ms))
.
Please note that if the current component is cleaned up before the throttled callback is called, the throttled callback will not be called.
There's also watch_throttled_with_options
where you can specify the other watch options (except filter
).
use leptos::*;
use leptos::logging::log;
use leptos_use::{watch_throttled_with_options, WatchThrottledOptions};
pub fn Demo() -> impl IntoView {
let (source, set_source) = create_signal(0);
watch_throttled_with_options(
move || source.get(),
move |_, _, _| {
log!("changed!");
},
500.0,
WatchThrottledOptions::default().leading(true).trailing(false),
);
view! { }
}
Recommended Reading
Server-Side Rendering
On the server the callback
will never be called except if you set immediate
to true
in which case the callback will be
called exactly once.
See also
Types
Source
watch_with_options
whenever
Shorthand for watching a signal to be true
.
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::whenever;
pub fn Demo() -> impl IntoView {
let (is_ready, set_ready) = create_signal(false);
whenever(move || is_ready.get(), |v, _, _| log!("{}", v));
view! { }
}
Callback Function
Same as watch
, the callback will be called with callback(input, prev_input, prev_return)
.
use leptos::*;
use leptos::logging::log;
use leptos_use::whenever;
pub fn Demo() -> impl IntoView {
let (is_ready, set_ready) = create_signal(false);
whenever(move || is_ready.get(), |value, prev_value, _| {
log!("before: {prev_value:?}; now: {value}");
});
view! { }
}
Computed
Same as watch
, you can pass a getter function to calculate on each change.
use leptos::*;
use leptos::logging::log;
use leptos_use::whenever;
pub fn Demo() -> impl IntoView {
let (counter, set_counter) = create_signal(0);
whenever(
move || counter.get() == 7,
|_, _, _| log!("counter is 7 now!"),
);
view! { }
}
Options
Options and defaults are same as watch_with_options
.
use leptos::*;
use leptos::logging::log;
use leptos_use::{WatchOptions, whenever_with_options};
pub fn Demo() -> impl IntoView {
let (counter, set_counter) = create_signal(0);
whenever_with_options(
move || counter.get() == 7,
|_, _, _| log!("counter is 7 now!"),
WatchOptions::default().immediate(true),
);
view! { }
}
Server-Side Rendering
On the server this works just fine except if you throttle or debounce in which case the callback
will never be called except if you set immediate
to true
in which case the callback will be
called exactly once.
Source
signal_debounced
Debounce changing of a Signal
value.
Demo
Usage
use leptos::*;
use leptos_use::signal_debounced;
#[component]
fn Demo() -> impl IntoView {
let (input, set_input) = create_signal("");
let debounced: Signal<&'static str> = signal_debounced(input, 1000.0);
view! { }
}
Options
The usual debounce option max_wait
is available.
use leptos::*;
use leptos_use::{signal_debounced_with_options, DebounceOptions};
#[component]
fn Demo() -> impl IntoView {
let (input, set_input) = create_signal("");
let debounced: Signal<&'static str> = signal_debounced_with_options(
input,
1000.0,
DebounceOptions::default().max_wait(Some(500.0))
);
view! { }
}
Recommended Reading
Server-Side Rendering
Internally this uses setTimeout
which is not supported on the server. So usually
a throttled signal on the server will simply be ignored.
Source
signal_throttled
Throttle changing of a Signal
value.
Demo
Usage
use leptos::*;
use leptos_use::signal_throttled;
#[component]
fn Demo() -> impl IntoView {
let (input, set_input) = create_signal("");
let throttled: Signal<&'static str> = signal_throttled(input, 1000.0);
view! { }
}
Options
The usual throttle options leading
and trailing
are available.
use leptos::*;
use leptos_use::{signal_throttled_with_options, ThrottleOptions};
#[component]
fn Demo() -> impl IntoView {
let (input, set_input) = create_signal("");
let throttled: Signal<&'static str> = signal_throttled_with_options(
input,
1000.0,
ThrottleOptions::default().leading(false).trailing(true)
);
view! { }
}
Recommended Reading
Server-Side Rendering
Internally this uses setTimeout
which is not supported on the server. So usually
a throttled signal on the server will simply be ignored.
Source
sync_signal
Two-way Signals synchronization.
Note: Please consider first if you can achieve your goals with the "Good Options" described in the Leptos book firstly. Only if you really have to, use this function. This is in effect the "If you really must...".
Demo
Usage
use leptos::*;
use leptos_use::sync_signal;
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(1);
let (b, set_b) = create_signal(2);
let stop = sync_signal((a, set_a), (b, set_b));
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 1, b: 1
set_b.set(3);
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 3, b: 3
set_a.set(4);
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 4, b: 4
view! { }
}
RwSignal
You can mix and match RwSignal
s and Signal
-WriteSignal
pairs.
use leptos::*;
use leptos_use::sync_signal;
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(1);
let (b, set_b) = create_signal(2);
let c_rw = create_rw_signal(3);
let d_rw = create_rw_signal(4);
sync_signal((a, set_a), c_rw);
sync_signal(d_rw, (b, set_b));
sync_signal(c_rw, d_rw);
view! { }
}
One directional
You can synchronize a signal only from left to right or right to left.
use leptos::*;
use leptos_use::{sync_signal_with_options, SyncSignalOptions, SyncDirection};
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(1);
let (b, set_b) = create_signal(2);
let stop = sync_signal_with_options(
(a, set_a),
(b, set_b),
SyncSignalOptions::default().direction(SyncDirection::LeftToRight)
);
set_b.set(3); // doesn't sync
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 1, b: 3
set_a.set(4);
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 4, b: 4
view! { }
}
Custom Transform
You can optionally provide custom transforms between the two signals.
use leptos::*;
use leptos_use::{sync_signal_with_options, SyncSignalOptions};
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(10);
let (b, set_b) = create_signal(2);
let stop = sync_signal_with_options(
(a, set_a),
(b, set_b),
SyncSignalOptions::default()
.transform_ltr(|left| *left * 2)
.transform_rtl(|right| *right / 2)
);
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 10, b: 20
set_b.set(30);
logging::log!("a: {}, b: {}", a.get(), b.get()); // a: 15, b: 30
view! { }
}
Different Types
SyncSignalOptions::default()
is only defined if the two signal types are identical or
implement From
for each other. Otherwise, you have to initialize the options with
with_transforms
instead of default
.
use leptos_use::SyncSignalOptions;
use std::str::FromStr;
let options = SyncSignalOptions::with_transforms(
|left: &String| i32::from_str(left).unwrap_or_default(),
|right: &i32| right.to_string(),
);
Types
Source
use_sorted
Reactive sort of iterable
Demo
Usage
use leptos::*;
use leptos_use::use_sorted;
#[component]
fn Demo() -> impl IntoView {
let source = vec![10, 3, 5, 7, 2, 1, 8, 6, 9, 4];
let sorted = use_sorted(source); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
view! { }
}
You can also sort by key or with a compare function.
use leptos::*;
use leptos_use::{use_sorted_by, use_sorted_by_key};
#[derive(Clone, PartialEq)]
pub struct Person {
pub name: String,
pub age: u16,
}
#[component]
fn Demo() -> impl IntoView {
let source = vec![
Person {
name: "John".to_string(),
age: 40,
},
Person {
name: "Jane".to_string(),
age: 20,
},
Person {
name: "Joe".to_string(),
age: 30,
},
Person {
name: "Jenny".to_string(),
age: 22,
},
];
// sort by key
let sorted = use_sorted_by_key(
source.clone(),
|person| person.age,
);
// sort with compare function
let sorted = use_sorted_by(
source,
|p1, p2| p1.age.cmp(&p2.age),
);
view! { }
}
Please note that these two ways of sorting are equivalent.
Source
is_err
Reactive Result::is_err()
.
Usage
use leptos::*;
use leptos_use::is_err;
#[component]
fn Demo() -> impl IntoView {
let (example, set_example) = create_signal(
if js_sys::Math::random() < 0.5 { Ok("Example") } else { Err(()) }
);
let is_error = is_err(example);
view! { }
}
Source
is_none
Reactive Option::is_none()
.
Usage
use leptos::*;
use leptos_use::is_none;
#[component]
fn Demo() -> impl IntoView {
let (example, set_example) = create_signal(
if js_sys::Math::random() < 0.5 { Some("Example") } else { None }
);
let is_empty = is_none(example);
view! { }
}
Source
is_ok
Reactive Result::is_ok()
.
Usage
use leptos::*;
use leptos_use::is_ok;
#[component]
fn Demo() -> impl IntoView {
let (example, set_example) = create_signal(
if js_sys::Math::random() < 0.5 { Ok("Example") } else { Err(()) }
);
let is_ok = is_ok(example);
view! { }
}
Source
is_some
Reactive Option::is_some()
.
Usage
use leptos::*;
use leptos_use::is_some;
#[component]
fn Demo() -> impl IntoView {
let (example, set_example) = create_signal(
if js_sys::Math::random() < 0.5 { Some("Example") } else { None }
);
let not_empty = is_some(example);
view! { }
}
Source
use_cycle_list
Cycle through a list of items.
Demo
Usage
use leptos::*;
use leptos::logging::log;
use leptos_use::{use_cycle_list, UseCycleListReturn};
#[component]
fn Demo() -> impl IntoView {
let UseCycleListReturn { state, next, prev, .. } = use_cycle_list(
vec!["Dog", "Cat", "Lizard", "Shark", "Whale", "Dolphin", "Octopus", "Seal"]
);
log!("{}", state.get()); // "Dog"
prev();
log!("{}", state.get()); // "Seal"
view! { }
}
Types
Source
use_debounce_fn
Debounce execution of a function.
Debounce is an overloaded waiter: If you keep asking him your requests will be ignored until you stop and give him some time to think about your latest inquiry.
Demo
Usage
use leptos::*;
use leptos::ev::resize;
use leptos_use::use_debounce_fn;
#[component]
fn Demo() -> impl IntoView {
let mut debounced_fn = use_debounce_fn(
|| {
// do something
},
1000.0,
);
window_event_listener(resize, move |_| { debounced_fn(); });
view! { }
}
Please note that if the current component is cleaned up before the throttled callback is called, the throttled callback will not be called.
You can also pass options to use_debounce_fn_with_options
with a maximum wait time, similar to
lodash debounce.
use leptos::*;
use leptos::ev::resize;
use leptos_use::use_debounce_fn_with_options;
use leptos_use::utils::DebounceOptions;
#[component]
fn Demo() -> impl IntoView {
let mut debounced_fn = use_debounce_fn_with_options(
|| {
// do something
},
1000.0,
DebounceOptions::default()
.max_wait(Some(5000.0)),
);
window_event_listener(resize, move |_| { debounced_fn(); });
view! { }
}
Currently there is no way to use a function with a return value. Please open an issue if you need this.
If you want to throttle a function that takes an argument there are also the versions
use_debounce_fn_with_arg
and use_debounce_fn_with_arg_and_options
.
Recommended Reading
Server-Side Rendering
Internally this uses setTimeout
which is not supported on the server. So usually calling
a debounced function on the server will simply be ignored.
Source
use_supported
SSR compatibe is_supported
Usage
use leptos::*;
use leptos_use::{use_supported, js};
use wasm_bindgen::JsValue;
pub fn Demo() -> impl IntoView {
let is_supported = use_supported(
|| js!("getBattery" in &window().navigator())
);
if is_supported.get() {
// do something
}
view! { }
}
Source
use_throttle_fn
Throttle execution of a function. Especially useful for rate limiting execution of handlers on events like resize and scroll.
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.
Demo
Usage
use leptos::*;
use leptos_use::use_throttle_fn;
#[component]
fn Demo() -> impl IntoView {
let mut throttled_fn = use_throttle_fn(
|| {
// do something, it will be called at most 1 time per second
},
1000.0,
);
view! {
<button on:click=move |_| { throttled_fn(); }>
"Smash me!"
</button>
}
}
Please note that if the current component is cleaned up before the throttled callback is called, the throttled callback will not be called.
You can provide options when you use use_throttle_fn_with_options
.
use leptos::*;
use leptos_use::{ThrottleOptions, use_throttle_fn_with_options};
#[component]
fn Demo() -> impl IntoView {
let throttled_fn = use_throttle_fn_with_options(
|| {
// do something, it will be called at most 1 time per second
},
1000.0,
ThrottleOptions::default()
.leading(true)
.trailing(true),
);
view! { }
}
If you want to throttle a function that takes an argument there are also the versions
use_throttle_fn_with_arg
and use_throttle_fn_with_arg_and_options
.
Recommended Reading
Server-Side Rendering
Internally this uses setTimeout
which is not supported on the server. So usually calling
a throttled function on the server will simply be ignored.
Source
use_to_string
Reactive ToString::to_string()
.
Usage
use leptos::*;
use leptos_use::use_to_string;
#[component]
fn Demo() -> impl IntoView {
let (number, set_number) = create_signal(3.14_f64);
let str = use_to_string::<_, f64>(number);
view! { }
}
Source
use_intl_number_format
Reactive Intl.NumberFormat
.
Demo
Usage
In basic use without specifying a locale, a formatted string in the default locale and with default options is returned.
use leptos::*;
use leptos_use::{use_intl_number_format, UseIntlNumberFormatOptions};
#[component]
fn Demo() -> impl IntoView {
let (number, set_number) = create_signal(3500);
let number_format = use_intl_number_format(UseIntlNumberFormatOptions::default());
let formatted = number_format.format::<u16>(number); // "3,500" if in US English locale
view! { }
}
Using locales
This example shows some of the variations in localized number formats. In order to get the format
of the language used in the user interface of your application, make sure to specify that language
(and possibly some fallback languages) using the locales
argument:
use leptos::*;
use leptos_use::{use_intl_number_format, UseIntlNumberFormatOptions};
#[component]
fn Demo() -> impl IntoView {
let number = 123456.789_f32;
// German uses comma as decimal separator and period for thousands
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default().locale("de-DE"),
);
let formatted = number_format.format(number); // 123.456,789
// Arabic in most Arabic speaking countries uses real Arabic digits
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default().locale("ar-EG"),
);
let formatted = number_format.format(number); // Ω‘Ω’Ω£Ω€Ω₯Ω¦Ω«Ω§Ω¨Ω©
// India uses thousands/lakh/crore separators
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default().locale("en-IN"),
);
let formatted = number_format.format(number); // 1,23,456.789
// the nu extension key requests a numbering system, e.g. Chinese decimal
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default().locale("zh-Hans-CN-u-nu-hanidec"),
);
let formatted = number_format.format(number); // δΈδΊδΈ,εδΊε
.δΈε
«δΉ
// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default().locales(vec!["ban".to_string(), "id".to_string()]),
);
let formatted = number_format.format(number); // 123.456,789
view! { }
}
Using options
The results can be customized in multiple ways.
use leptos::*;
use leptos_use::{NumberStyle, UnitDisplay, use_intl_number_format, UseIntlNumberFormatOptions};
#[component]
fn Demo() -> impl IntoView {
let number = 123456.789_f64;
// request a currency format
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default()
.locale("de-DE")
.style(NumberStyle::Currency)
.currency("EUR"),
);
let formatted = number_format.format(number); // 123.456,79 β¬
// the Japanese yen doesn't use a minor unit
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default()
.locale("ja-JP")
.style(NumberStyle::Currency)
.currency("JPY"),
);
let formatted = number_format.format(number); // οΏ₯123,457
// limit to three significant digits
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default()
.locale("en-IN")
.maximum_significant_digits(3),
);
let formatted = number_format.format(number); // 1,23,000
// Formatting with units
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default()
.locale("pt-PT")
.style(NumberStyle::Unit)
.unit("kilometer-per-hour"),
);
let formatted = number_format.format(50); // 50 km/h
let number_format = use_intl_number_format(
UseIntlNumberFormatOptions::default()
.locale("en-GB")
.style(NumberStyle::Unit)
.unit("liter")
.unit_display(UnitDisplay::Long),
);
let formatted = number_format.format(16); // 16 litres
view! { }
}
For an exhaustive list of options see UseIntlNumberFormatOptions
.
Formatting ranges
Apart from the format
method, the format_range
method can be used to format a range of numbers.
Please see UseIntlNumberFormatReturn::format_range
for details.
Server-Side Rendering
Since Intl.NumberFormat
is a JavaScript API it is not available on the server. That's why
it falls back to a simple call to format!()
on the server.
Types
enum CompactDisplay
enum CurrencyDisplay
enum CurrencySign
enum LocaleMatcher
enum Notation
enum SignDisplay
enum NumberStyle
enum UnitDisplay
enum NumberGrouping
enum RoundingMode
enum RoundingPriority
enum TrailingZeroDisplay
struct UseIntlNumberFormatOptions
Source
use_abs
Reactive abs()
.
Demo
Usage
use leptos::*;
use leptos_use::math::use_abs;
#[component]
fn Demo() -> impl IntoView {
let (value, set_value) = create_signal(-32.25);
let result: Signal<f64> = use_abs(value); // 32.25
assert_eq!(result.get(), 32.25);
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_and
Reactive AND
condition.
Demo
Usage
use leptos::*;
use leptos_use::math::use_and;
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(true);
let (b, set_b) = create_signal(false);
let a_and_b = use_and(a, b);
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_ceil
Reactive ceil()
.
Demo
Usage
use leptos::*;
use leptos_use::math::use_ceil;
#[component]
fn Demo() -> impl IntoView {
let (value, set_value) = create_signal(44.15);
let result: Signal<f64> = use_ceil(value); // 45
assert_eq!(result.get(), 45.0);
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_floor
Reactive floor()
.
Demo
Usage
use leptos::*;
use leptos_use::math::use_floor;
#[component]
fn Demo() -> impl IntoView {
let (value, set_value) = create_signal(45.95);
let result: Signal<f64> = use_floor(value); // 45
assert_eq!(result.get(), 45.0);
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_max
Reactive max()
.
Works with any container that implements IntoIterator
(Vec
, HashSet
, ...)
with any elements that implement PartialOrd
and Clone
(floats, ints, strings, ...).
If the container is empty or only contains non comparable values like NaN
, it returns None
.
Otherwise it returns the Some(<largest value>)
in the container.
Usage
use leptos::*;
use leptos_use::math::use_max;
#[component]
fn Demo() -> impl IntoView {
let (values, set_values) = create_signal(vec![1.0, 2.0, 3.0, f32::NAN, 4.0, 5.0]);
let result = use_max::<Vec<f32>, _, _>(values); // Some(5.0)
assert_eq!(result.get(), Some(5.0));
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_min
Reactive min()
.
Works with any container that implements IntoIterator
(Vec
, HashSet
, ...)
with any elements that implement PartialOrd
and Clone
(floats, ints, strings, ...).
If the container is empty or only contains non comparable values like NaN
, it returns None
.
Otherwise it returns the Some(<smallest value>)
in the container.
Usage
use leptos::*;
use leptos_use::math::use_min;
#[component]
fn Demo() -> impl IntoView {
let (values, set_values) = create_signal(vec![1.0, 2.0, 3.0, f32::NAN, 4.0, 5.0]);
let result = use_min::<Vec<f32>, _, _>(values); // Some(1.0)
assert_eq!(result.get(), Some(1.0));
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_not
Reactive NOT
condition.
Demo
Usage
use leptos::*;
use leptos_use::math::use_not;
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(true);
let not_a = use_not(a);
view! { }
}
See also
Feature
This function is only available if the crate feature
math
is enabled
Source
use_or
Reactive OR
condition.
Demo
Usage
use leptos::*;
use leptos_use::math::use_or;
#[component]
fn Demo() -> impl IntoView {
let (a, set_a) = create_signal(true);
let (b, set_b) = create_signal(false);
let a_or_b = use_or(a, b);
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled
Source
use_round
Reactive round()
.
Demo
Usage
use leptos::*;
use leptos_use::math::use_round;
#[component]
fn Demo() -> impl IntoView {
let (value, set_value) = create_signal(45.95);
let result: Signal<f64> = use_round(value); // 46
assert_eq!(result.get(), 46.0);
view! { }
}
Feature
This function is only available if the crate feature
math
is enabled