Crate leptos_reactive

Expand description

The reactive system for the Leptos Web framework.

Fine-Grained Reactivity

Leptos is built on a fine-grained reactive system, which means that individual reactive values (“signals,” sometimes known as observables) trigger the code that reacts to them (“effects,” sometimes known as observers) to re-run. These two halves of the reactive system are inter-dependent. Without effects, signals can change within the reactive system but never be observed in a way that interacts with the outside world. Without signals, effects run once but never again, as there’s no observable value to subscribe to.

Here are the most commonly-used functions and types you’ll need to build a reactive system:

Signals

Signals: create_signal, which returns a (ReadSignal, WriteSignal) tuple, or create_rw_signal, which returns a signal RwSignal without this read-write segregation.
Derived Signals: any function that relies on another signal.
Memos: create_memo, which returns a Memo.
Resources: create_resource, which converts an async std::future::Future into a synchronous Resource signal.

Effects

Use create_effect when you need to synchronize the reactive system with something outside it (for example: logging to the console, writing to a file or local storage)
The Leptos DOM renderer wraps any Fn in your template with create_effect, so components you write do not need explicit effects to synchronize with the DOM.

Example

use leptos_reactive::*;

// creates a new reactive Scope
// this is omitted from most of the examples in the docs
// you usually won't need to call it yourself
create_scope(create_runtime(), |cx| {
  // a signal: returns a (getter, setter) pair
  let (count, set_count) = create_signal(cx, 0);

  // calling the getter gets the value
  assert_eq!(count(), 0);
  // calling the setter sets the value
  set_count(1);
  // or we can mutate it in place with update()
  set_count.update(|n| *n += 1);

  // a derived signal: a plain closure that relies on the signal
  // the closure will run whenever we *access* double_count()
  let double_count = move || count() * 2;
  assert_eq!(double_count(), 4);
   
  // a memo: subscribes to the signal
  // the closure will run only when count changes
  let memoized_triple_count = create_memo(cx, move |_| count() * 3);
  assert_eq!(memoized_triple_count(), 6);

  // this effect will run whenever count() changes
  create_effect(cx, move |_| {
    println!("Count = {}", count());
  });
});

Re-exports

pub extern crate tracing;

Structs

Memo

An efficient derived reactive value based on other reactive values.

ReadSignal

The getter for a reactive signal.

Resource

A signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.

ResourceId

Unique ID assigned to a Resource.

RuntimeId

Unique ID assigned to a Runtime.

RwSignal

A signal that combines the getter and setter into one value, rather than separating them into a ReadSignal and a WriteSignal. You may prefer this its style, or it may be easier to pass around in a context or as a function argument.

Scope

A Each scope can have child scopes, and may in turn have a parent.

ScopeDisposer

Creating a Scope gives you a disposer, which can be called to dispose of that reactive scope.

ScopeId

Unique ID assigned to a Scope.

Signal

A wrapper for any kind of readable reactive signal: a ReadSignal, Memo, RwSignal, or derived signal closure.

SignalId

Unique ID assigned to a signal.

SignalSetter

A wrapper for any kind of settable reactive signal: a WriteSignal, RwSignal, or closure that receives a value and sets a signal depending on it.

StoredValue

A non-reactive wrapper for any value, which can be created with store_value.

SuspenseContext

Tracks Resources that are read under a suspense context, i.e., within a Suspense component.

WriteSignal

The setter for a reactive signal.

Enums

MaybeSignal

A wrapper for a value that is either T or Signal<T>.

SerializationError

Describes errors that can occur while serializing and deserializing data, typically during the process of streaming Resources from the server to the client.

Traits

IntoSignal

Helper trait for converting Fn() -> T closures into Signal<T>.

IntoSignalSetter

Helper trait for converting Fn(T) into SignalSetter<T>.

Serializable

Describes an object that can be serialized to or from a supported format Currently those are JSON and Cbor

UntrackedGettableSignal

Trait implemented for all signal types which you can get a value from, such as ReadSignal, Memo, etc., which allows getting the inner value without subscribing to the current scope.

UntrackedSettableSignal

Trait implemented for all signal types which you can set the inner value, such as WriteSignal and RwSignal, which allows setting the inner value without causing effects which depend on the signal from being run.

Functions

create_effect

Effects run a certain chunk of code whenever the signals they depend on change. create_effect immediately runs the given function once, tracks its dependence on any signal values read within it, and reruns the function whenever the value of a dependency changes.

create_isomorphic_effect

Creates an effect; unlike effects created by create_effect, isomorphic effects will run on the server as well as the client.

create_local_resource

Creates a local Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.

create_local_resource_with_initial_value

Creates a local Resource with the given initial value, which will only generate and run a Future using the fetcher when the source changes.

create_memo

Creates an efficient derived reactive value based on other reactive values.

create_resource

Creates Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.

create_resource_with_initial_value

Creates a Resource with the given initial value, which will only generate and run a Future using the fetcher when the source changes.

create_rw_signal

Creates a reactive signal with the getter and setter unified in one value. You may prefer this style, or it may be easier to pass around in a context or as a function argument.

create_selector

Creates a conditional signal that only notifies subscribers when a change in the source signal’s value changes whether it is equal to the key value (as determined by PartialEq.)

create_selector_with_fn

Creates a conditional signal that only notifies subscribers when a change in the source signal’s value changes whether the given function is true.

create_signal

Creates a signal, the basic reactive primitive.

create_signal_from_stream

Creates a signal that always contains the most recent value emitted by a Stream. If the stream has not yet emitted a value since the signal was created, the signal’s value will be None.

create_slice

Derives a reactive slice of an RwSignal.

on_cleanup

Creates a cleanup function, which will be run when a Scope is disposed.

provide_context

Provides a context value of type T to the current reactive Scope and all of its descendants. This can be consumed using use_context.

queue_microtask

Exposes the queueMicrotask method in the browser, and simply runs the given function when on the server.

spawn_local

Spawns and runs a thread-local std::future::Future in a platform-independent way.

store_value

Creates a non-reactive wrapper for any value by storing it within the reactive system.

use_context

Extracts a context value of type T from the reactive system by traversing it upwards, beginning from the current Scope and iterating through its parents, if any. The context value should have been provided elsewhere using provide_context.