Crate dioxus_signals

Expand description

§Dioxus Signals

Dioxus Signals is an ergonomic Copy runtime for data with local subscriptions.

§Copy Data

All signals implement Copy, even if the inner value does not implement copy. This makes it easy to move any data into futures or children.

use dioxus::prelude::*;
use dioxus_signals::*;

#[component]
fn App() -> Element {
    let signal = use_signal(|| "hello world".to_string());

    spawn(async move {
        // signal is Copy even though String is not copy
        print!("{signal}");
    });

    rsx! {
        "{signal}"
    }
}

§Local Subscriptions

Signals will only subscribe to components when you read from the signal in that component. It will never subscribe to a component when reading data in a future or event handler.

use dioxus::prelude::*;
use dioxus_signals::*;

#[component]
fn App() -> Element {
    // Because signal is never read in this component, this component will not rerun when the signal changes
    let mut signal = use_signal(|| 0);

    rsx! {
        button {
            onclick: move |_| {
                signal += 1;
            },
            "Increase"
        }
        for id in 0..10 {
            Child {
                signal,
            }
        }
    }
}

#[derive(Props, Clone, PartialEq)]
struct ChildProps {
    signal: Signal<usize>,
}

fn Child(props: ChildProps) -> Element {
    // This component does read from the signal, so when the signal changes it will rerun
    rsx! {
        "{props.signal}"
    }
}

Because subscriptions happen when you read from (not create) the data, you can provide signals through the normal context API:

use dioxus::prelude::*;
use dioxus_signals::*;

#[component]
fn App() -> Element {
    // Because signal is never read in this component, this component will not rerun when the signal changes
    use_context_provider(|| Signal::new(0));

    rsx! {
        Child {}
    }
}

#[component]
fn Child() -> Element {
    let signal: Signal<i32> = use_context();
    // This component does read from the signal, so when the signal changes it will rerun
    rsx! {
        "{signal}"
    }
}

§Computed Data

In addition to local subscriptions in components, dioxus-signals provides a way to derive data with local subscriptions.

The use_memo hook will only rerun when any signals inside the hook change:

use dioxus::prelude::*;
use dioxus_signals::*;

#[component]
fn App() -> Element {
    let mut signal = use_signal(|| 0);
    let doubled = use_memo(move || signal * 2);

    rsx! {
        button {
            onclick: move |_| signal += 1,
            "Increase"
        }
        Child {
            signal: doubled
        }
    }
}

#[component]
fn Child(signal: ReadSignal<usize>) -> Element {
    rsx! {
        "{signal}"
    }
}

Modules§

warnings: Warnings that can be triggered by suspicious usage of signals

Macros§

default_impl: This macro is used to generate a impl Default block for any type with the function new_maybe_sync that takes a generic T
eq_impls: This macro is used to generate impl PartialEq blocks for any Readable type that takes a generic T
fmt_impls: This macro is used to generate impl Display, and impl Debug blocks for any Readable type that takes a generic T
read_impls: This macro is used to generate impl Display, impl Debug, impl PartialEq, and impl Eq blocks for any Readable type that takes a generic T
write_impls: This macro is used to generate impl Add, impl AddAssign, impl Sub, impl SubAssign, impl Mul, impl MulAssign, impl Div, and impl DivAssign blocks for any Writable type that takes a generic T

Structs§

CopyValue: CopyValue is a wrapper around a value to make the value mutable and Copy.
Global: A lazy value that is created once per application and can be accessed from anywhere in that application
GlobalLazyContext: The context for global signals
MappedMutSignal: A read only signal that has been mapped to a new type.
MappedSignal: A read only signal that has been mapped to a new type.
Memo: Memos are the result of computing a value from use_memo.
Owner: Owner: Handles dropping generational boxes. The owner acts like a runtime lifetime guard. Any states that you create with an owner will be dropped when that owner is dropped.
ReadSignal: A boxed version of Readable that can be used to store any readable type.
ReadableValueIterator: An iterator over the values of a Readable<Vec<T>>.
SetCompare: An object that can efficiently compare a value to a set of values.
Signal: Signals are a Copy state management solution with automatic dependency tracking.
SignalData: The data stored for tracking in a signal.
SyncStorage: A thread safe storage. This is slower than the unsync storage, but allows you to share the value between threads.
UnsyncStorage: A unsync storage. This is the default storage type.
WritableValueIterator: An iterator over the values of a Writable<Vec<T>>.
WriteLock: A mutable reference to a writable value. This reference acts similarly to std::cell::RefMut, but it has extra debug information and integrates with the reactive system to automatically update dependents.
WriteSignal: A boxed version of Writable that can be used to store any writable type.

Enums§

BorrowError: An error that can occur when trying to borrow a value.
BorrowMutError: An error that can occur when trying to borrow a value mutably.
GlobalKey: A key used to identify a signal in the global signal context

Traits§

AnyStorage: A trait for any storage backing type.
BoxedSignalStorage: A trait for creating boxed readable and writable signals. This is implemented for UnsyncStorage and SyncStorage.
CreateBoxedSignalStorage: A trait for creating boxed readable and writable signals. This is implemented for UnsyncStorage and SyncStorage.
InitializeFromFunction: A trait for an item that can be constructed from an initialization function
Readable: A trait for states that can be read from like crate::Signal, crate::GlobalSignal, or crate::ReadSignal. You may choose to accept this trait as a parameter instead of the concrete type to allow for more flexibility in your API. For example, instead of creating two functions, one that accepts a crate::Signal and one that accepts a crate::GlobalSignal, you can create one function that accepts a Readable type.
ReadableBoxExt: An extension trait for Readable types that can be boxed into a trait object.
ReadableExt: An extension trait for Readable types that provides some convenience methods.
ReadableHashMapExt: An extension trait for Readable<HashMap<K, V, H>> that provides some convenience methods.
ReadableHashSetExt: An extension trait for Readable<HashSet<V, H>> that provides some convenience methods.
ReadableOptionExt: An extension trait for Readable<Option<T>> that provides some convenience methods.
ReadableResultExt: An extension trait for Readable<Option<T>> that provides some convenience methods.
ReadableStrExt: An extension trait for Readable<String> and Readable<str> that provides some convenience methods.
ReadableStringExt: An extension trait for Readable<String> that provides some convenience methods.
ReadableVecExt: An extension trait for Readable<Vec<T>> that provides some convenience methods.
Storage: A trait for a storage backing type. (RefCell, RwLock, etc.)
Writable: A trait for states that can be written to like crate::Signal. You may choose to accept this trait as a parameter instead of the concrete type to allow for more flexibility in your API.
WritableBoxedExt: An extension trait for Writable values that can be boxed into a trait object.
WritableExt: An extension trait for Writable that provides some convenience methods.
WritableHashMapExt: An extension trait for Writable<HashMap<K, V, H>> that provides some convenience methods.
WritableHashSetExt: An extension trait for Writable<HashSet<V, H>> that provides some convenience methods.
WritableOptionExt: An extension trait for Writable<Option<T>>` that provides some convenience methods.
WritableStringExt: An extension trait for Writable<String> that provides some convenience methods.
WritableVecExt: An extension trait for Writable<Vec<T>> that provides some convenience methods.

Functions§

get_global_context: Get the global context for signals

Type Aliases§

GlobalMemo: A memo that can be accessed from anywhere in the application and created in a static
GlobalSignal: A signal that can be accessed from anywhere in the application and created in a static
ReadOnlySignalDeprecated: A signal that can only be read from.
ReadableRef: A reference to a value that can be read from.
SyncSignal: A signal that can safely shared between threads.
WritableRef: A reference to a value that can be written to.