Crate dioxus_signals

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: ReadOnlySignal<usize>) -> Element {
    rsx! {
        "{signal}"
    }
}

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.
• GlobalMemo
  A signal 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
• MappedSignal
  A read only signal that has been mapped to a new type.
• Memo
  A value that is memoized. This is useful for caching the result of a computation.
• 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.
• ReactiveContext
  A context for signal reads and writes to be directed to
• ReadOnlySignal
  A signal that can only be read from.
• ReadableValueIterator
  An iterator over the values of a Readable<Vec<T>>.
• Signal
  Creates a new 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>>.
• Write
  A mutable reference to a signal’s value.

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.

Traits

• AnyStorage
  A trait for any storage backing type.
• Readable
  A trait for states that can be read from like crate::Signal, crate::GlobalSignal, or crate::ReadOnlySignal. 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.
• ReadableOptionExt
  An extension trait for Readable<Option> that provides some convenience methods.
• ReadableVecExt
  An extension trait for Readable<Vec> that provides some convenience methods.
• Storage
  A trait for a storage backing type. (RefCell, RwLock, etc.)
• Writable
  A trait for states that can be read from like crate::Signal, or crate::GlobalSignal. 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 Writable type.
• WritableOptionExt
  An extension trait for Writable<Option> that provides some convenience methods.
• WritableVecExt
  An extension trait for Writable<Vec> that provides some convenience methods.

Type Aliases

• 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 read from.