Struct freya::prelude::Signal

pub struct Signal<T, S = UnsyncStorage>
where
    T: 'static,
    S: Storage<SignalData<T>>,
{ /* private fields */ }

Signals are a Copy state management solution with automatic dependency tracking.

You may have noticed that this struct doesn’t have many methods. Most methods for Signal are defined on the Readable and Writable traits.

Reading and Writing to a Signal

Signals are similar to a copy version of Rc<RefCell<T>> built for UIs. You can read and write to a signal like a RefCell:

let mut signal = use_signal(|| 0);

{
    // This will read the value (we use a block to make sure the read is dropped before the write. You can read more about this in the next section)
    let read = signal.read();
    // Just like refcell, read you can deref the read to get the inner &T reference
    match &*read {
        &0 => println!("read is 0"),
        &1 => println!("read is 1"),
        _ => println!("read is something else ({read})"),
    }
}

// This will write to the value
let mut write = signal.write();
// Again, we can deref the write to get the inner &mut T reference
*write += 1;

Signals also have a bunch of helper methods to make it easier to use. Calling it like a function will clone the inner value. You can also call a few traits like AddAssign on it directly without writing to it manually:

let mut signal = use_signal(|| 0);
// This will clone the value
let clone: i32 = signal();

// You can directly display the signal
println!("{}", signal);

let signal_vec = use_signal(|| vec![1, 2, 3]);
// And use vec methods like .get and .len without reading the signal explicitly
let first = signal_vec.get(0);
let last = signal_vec.last();
let len = signal_vec.len();

// You can also iterate over signals directly
for i in signal_vec.iter() {
    println!("{}", i);
}

For a full list of all the helpers available, check out the Readable, ReadableVecExt, ReadableOptionExt, Writable, WritableVecExt, and WritableOptionExt traits.

Just like RefCell<T>, Signal checks borrows at runtime. If you read and write to the signal at the same time, it will panic:

let mut signal = use_signal(|| 0);
// If you create a read and hold it while you write to the signal, it will panic
let read = signal.read_unchecked();
// This will panic
signal += 1;
println!("{}", read);

To avoid issues with overlapping reads and writes, you can use the with_* variants of methods to read and write to the signal in a single scope or wrap your reads and writes inside a block:

let mut signal = use_signal(|| 0);
{
    // Since this read is inside a block that ends before we write to the signal, the signal will be dropped before the write and it will not panic
    let read = signal.read();
    println!("{}", read);
}
signal += 1;

// Or you can use the with and with_write methods which only read or write to the signal inside the closure
signal.with(|read| println!("{}", read));
// Since the read only lasts as long as the closure, this will not panic
signal.with_mut(|write| *write += 1);

Signals with Async

Because signals check borrows at runtime, you need to be careful when reading and writing to signals inside of async code. If you hold a read or write to a signal over an await point, that read or write may still be open while you run other parts of your app:

async fn double_me_async(value: &mut u32) {
    sleep(100).await;
    *value *= 2;
}
let mut signal = use_signal(|| 0);

use_future(move || async move {
    // Don't hold reads or writes over await points
    let mut write = signal.write();
    // While the future is waiting for the async work to finish, the write will be open
    double_me_async(&mut write).await;
});

rsx!{
    // This read may panic because the write is still active while the future is waiting for the async work to finish
    "{signal}"
};

Instead of holding a read or write over an await point, you can clone whatever values you need out of your signal and then set the signal to the result once the async work is done:

async fn double_me_async(value: u32) -> u32 {
    sleep(100).await;
    value * 2
}
let mut signal = use_signal(|| 0);

use_future(move || async move {
    // Clone the value out of the signal
    let current_value = signal();
    // Run the async work
    let new_value = double_me_async(current_value).await;
    // Set the signal to the new value
    signal.set(new_value);
});

rsx! {
    // This read will not panic because the write is never held over an await point
    "{signal}"
};

Signals lifecycle

Signals are implemented with generational-box which makes all values Copy even if the inner value is not Copy.

This is incredibly convenient for UI development, but it does come with some tradeoffs. The lifetime of the signal is tied to the lifetime of the component it was created in. If you drop the component that created the signal, the signal will be dropped as well. You might run into this if you try to pass a signal from a child component to a parent component and drop the child component. To avoid this you can create your signal higher up in your component tree, use global signals, or create a signal in a specific scope (like the ScopeId::ROOT) with Signal::new_in_scope

TLDR Don’t pass signals up in the component tree. It will cause issues:

fn MyComponent() -> Element {
    let child_signal = use_signal(|| None);

    rsx! {
        IncrementButton {
            child_signal
        }
    }
}

#[component]
fn IncrementButton(mut child_signal: Signal<Option<Signal<i32>>>) -> Element {
    let signal_owned_by_child = use_signal(|| 0);
    // Don't do this: it may cause issues if you drop the child component
    child_signal.set(Some(signal_owned_by_child));

    todo!()
}

Implementations

impl<T> Signal<T>

where T: 'static,

pub fn new(value: T) -> Signal<T>

Creates a new Signal. Signals are a Copy state management solution with automatic dependency tracking.

This function should generally only be called inside hooks. The signal that this function creates is owned by the current component and will only be dropped when the component is dropped. If you call this function outside of a hook many times, you will leak memory until the component is dropped.

fn MyComponent() {
    // ❌ Every time MyComponent runs, it will create a new signal that is only dropped when MyComponent is dropped
    let signal = Signal::new(0);
    use_context_provider(|| signal);
    // ✅ Since the use_context_provider hook only runs when the component is created, the signal will only be created once and it will be dropped when MyComponent is dropped
    let signal = use_context_provider(|| Signal::new(0));
}

pub fn new_in_scope(value: T, owner: ScopeId) -> Signal<T>

Create a new signal with a custom owner scope. The signal will be dropped when the owner scope is dropped instead of the current scope.

pub const fn global(constructor: fn() -> T) -> GlobalSignal<T>

Creates a new GlobalSignal that can be used anywhere inside your dioxus app. This signal will automatically be created once per app the first time you use it.

Example

// Create a new global signal that can be used anywhere in your app
static SIGNAL: GlobalSignal<i32> = Signal::global(|| 0);

fn App() -> Element {
    rsx! {
        button {
            onclick: move |_| *SIGNAL.write() += 1,
            "{SIGNAL}"
        }
    }
}

Global signals are generally not recommended for use in libraries because it makes it more difficult to allow multiple instances of components you define in your library.

impl<T> Signal<T>

where T: PartialEq + 'static,

pub const fn global_memo(constructor: fn() -> T) -> GlobalMemo<T>

Creates a new GlobalMemo that can be used anywhere inside your dioxus app. This memo will automatically be created once per app the first time you use it.

Example

static SIGNAL: GlobalSignal<i32> = Signal::global(|| 0);
// Create a new global memo that can be used anywhere in your app
static DOUBLED: GlobalMemo<i32> = Signal::global_memo(|| SIGNAL() * 2);

fn App() -> Element {
    rsx! {
        button {
            // When SIGNAL changes, the memo will update because the SIGNAL is read inside DOUBLED
            onclick: move |_| *SIGNAL.write() += 1,
            "{DOUBLED}"
        }
    }
}

Global memos are generally not recommended for use in libraries because it makes it more difficult to allow multiple instances of components you define in your library.

pub fn memo(f: impl FnMut() -> T + 'static) -> Memo<T>

Creates a new unsync Selector. The selector will be run immediately and whenever any signal it reads changes.

Selectors can be used to efficiently compute derived data from signals.

pub fn memo_with_location( f: impl FnMut() -> T + 'static, location: &'static Location<'static> ) -> Memo<T>

Creates a new unsync Selector with an explicit location. The selector will be run immediately and whenever any signal it reads changes.

Selectors can be used to efficiently compute derived data from signals.

impl<T, S> Signal<T, S>

where T: 'static, S: Storage<SignalData<T>>,

pub fn new_maybe_sync(value: T) -> Signal<T, S>

Creates a new Signal. Signals are a Copy state management solution with automatic dependency tracking.

pub fn new_with_caller( value: T, caller: &'static Location<'static> ) -> Signal<T, S>

Creates a new Signal with an explicit caller. Signals are a Copy state management solution with automatic dependency tracking.

This method can be used to provide the correct caller information for signals that are created in closures:

#[track_caller]
fn use_my_signal(function: impl FnOnce() -> i32) -> Signal<i32> {
    // We capture the caller information outside of the closure so that it points to the caller of use_my_custom_hook instead of the closure
    let caller = std::panic::Location::caller();
    use_hook(move || Signal::new_with_caller(function(), caller))
}

pub fn new_maybe_sync_in_scope(value: T, owner: ScopeId) -> Signal<T, S>

Create a new signal with a custom owner scope. The signal will be dropped when the owner scope is dropped instead of the current scope.

pub fn new_maybe_sync_in_scope_with_caller( value: T, owner: ScopeId, caller: &'static Location<'static> ) -> Signal<T, S>

Create a new signal with a custom owner scope and a custom caller. The signal will be dropped when the owner scope is dropped instead of the current scope.

pub fn manually_drop(&self) -> Option<T>

Drop the value out of the signal, invalidating the signal in the process.

pub fn origin_scope(&self) -> ScopeId

Get the scope the signal was created in.

pub fn id(&self) -> GenerationalBoxId

Get the generational id of the signal.

pub fn write_silent(&self) -> <S as AnyStorage>::Mut<'static, T>

👎Deprecated: This pattern is no longer recommended. Prefer peek or creating new signals instead.

This pattern is no longer recommended. Prefer peek or creating new signals instead.

This function is the equivalent of the write_silent method on use_ref.

What you should use instead

Reading and Writing to data in the same scope

Reading and writing to the same signal in the same scope will cause that scope to rerun forever:

let mut signal = use_signal(|| 0);
// This makes the scope rerun whenever we write to the signal
println!("{}", *signal.read());
// This will rerun the scope because we read the signal earlier in the same scope
*signal.write() += 1;

You may have used the write_silent method to avoid this infinite loop with use_ref like this:

let signal = use_signal(|| 0);
// This makes the scope rerun whenever we write to the signal
println!("{}", *signal.read());
// Write silent will not rerun any subscribers
*signal.write_silent() += 1;

Instead you can use the peek and write methods instead. The peek method will not subscribe to the current scope which will avoid an infinite loop if you are reading and writing to the same signal in the same scope.

let mut signal = use_signal(|| 0);
// Peek will read the value but not subscribe to the current scope
println!("{}", *signal.peek());
// Write will update any subscribers which does not include the current scope
*signal.write() += 1;

Reading and Writing to different data

Why is this pattern no longer recommended?

This pattern is no longer recommended because it is very easy to allow your state and UI to grow out of sync. write_silent globally opts out of automatic state updates which can be difficult to reason about.

Lets take a look at an example: main.rs:

fn app() -> Element {
    let signal = use_context_provider(|| Signal::new(0));

    // We want to log the value of the signal whenever the app component reruns
    println!("{}", *signal.read());

    rsx! {
        button {
            // If we don't want to rerun the app component when the button is clicked, we can use write_silent
            onclick: move |_| *signal.write_silent() += 1,
            "Increment"
        }
        Child {}
    }
}

child.rs:

fn Child() -> Element {
    let signal: Signal<i32> = use_context();

    // It is difficult to tell that changing the button to use write_silent in the main.rs file will cause UI to be out of sync in a completely different file
    rsx! {
        "{signal}"
    }
}

Instead peek locally opts out of automatic state updates explicitly for a specific read which is easier to reason about.

Here is the same example using peek: main.rs:

fn app() -> Element {
    let mut signal = use_context_provider(|| Signal::new(0));

    // We want to log the value of the signal whenever the app component reruns, but we don't want to rerun the app component when the signal is updated so we use peek instead of read
    println!("{}", *signal.peek());

    rsx! {
        button {
            // We can use write like normal and update the child component automatically
            onclick: move |_| *signal.write() += 1,
            "Increment"
        }
        Child {}
    }
}

child.rs:

fn Child() -> Element {
    let signal: Signal<i32> = use_context();

    rsx! {
        "{signal}"
    }
}

Trait Implementations

impl<T, S> Add<T> for Signal<T, S>

where T: Add<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

type Output = T

The resulting type after applying the + operator.

fn add(self, rhs: T) -> <Signal<T, S> as Add<T>>::Output

Performs the + operation.

impl<T, S> AddAssign<T> for Signal<T, S>

where T: Add<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

fn add_assign(&mut self, rhs: T)

Performs the += operation.

impl<T, S> Clone for Signal<T, S>

where T: 'static, S: Storage<SignalData<T>>,

fn clone(&self) -> Signal<T, S>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T, S> Debug for Signal<T, S>

where T: Debug + 'static, S: Storage<SignalData<T>>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T, S> Default for Signal<T, S>

where T: Default + 'static, S: Storage<SignalData<T>>,

fn default() -> Signal<T, S>

Returns the “default value” for a type.

impl<T, S> Deref for Signal<T, S>

where T: Clone, S: Storage<SignalData<T>> + 'static,

Allow calling a signal with signal() syntax

Currently only limited to copy types, though could probably specialize for string/arc/rc

type Target = dyn Fn() -> T

The resulting type after dereferencing.

fn deref(&self) -> &<Signal<T, S> as Deref>::Target

Dereferences the value.

impl<T, S> Display for Signal<T, S>

where T: Display + 'static, S: Storage<SignalData<T>>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T, S> Div<T> for Signal<T, S>

where T: Div<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

type Output = T

The resulting type after applying the / operator.

fn div(self, rhs: T) -> <Signal<T, S> as Div<T>>::Output

Performs the / operation.

impl<T, S> DivAssign<T> for Signal<T, S>

where T: Div<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

fn div_assign(&mut self, rhs: T)

Performs the /= operation.

impl<T, S> From<Signal<T, S>> for ReadOnlySignal<T, S>

where T: 'static, S: Storage<SignalData<T>>,

fn from(inner: Signal<T, S>) -> ReadOnlySignal<T, S>

Converts to this type from the input type.

impl<T> IntoAttributeValue for Signal<T>

where T: Clone + IntoAttributeValue,

fn into_value(self) -> AttributeValue

Convert into an attribute value

impl<T> IntoDynNode for Signal<T>

where T: Clone + IntoDynNode,

fn into_dyn_node(self) -> DynamicNode

Consume this item and produce a DynamicNode

impl<T, S> Mul<T> for Signal<T, S>

where T: Mul<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

type Output = T

The resulting type after applying the * operator.

fn mul(self, rhs: T) -> <Signal<T, S> as Mul<T>>::Output

Performs the * operation.

impl<T, S> MulAssign<T> for Signal<T, S>

where T: Mul<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

fn mul_assign(&mut self, rhs: T)

Performs the *= operation.

impl<T, S> PartialEq for Signal<T, S>

where T: 'static, S: Storage<SignalData<T>>,

fn eq(&self, other: &Signal<T, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, S> Readable for Signal<T, S>

where S: Storage<SignalData<T>>,

fn try_peek_unchecked( &self ) -> Result<<<Signal<T, S> as Readable>::Storage as AnyStorage>::Ref<'static, <Signal<T, S> as Readable>::Target>, BorrowError>

Get the current value of the signal. Unlike read, this will not subscribe the current scope to the signal which can cause parts of your UI to not update.

If the signal has been dropped, this will panic.

type Target = T

The target type of the reference.

type Storage = S

The type of the storage this readable uses.

fn try_read_unchecked( &self ) -> Result<<<Signal<T, S> as Readable>::Storage as AnyStorage>::Ref<'static, <Signal<T, S> as Readable>::Target>, BorrowError>

Try to get a reference to the value without checking the lifetime. This will subscribe the current scope to the signal.

fn map<O>( self, f: impl Fn(&Self::Target) -> &O + 'static ) -> MappedSignal<O, Self::Storage>

where Self: Sized + Clone + 'static,

Map the readable type to a new type. This lets you provide a view into a readable type without needing to clone the inner value.

fn read(&self) -> <Self::Storage as AnyStorage>::Ref<'_, Self::Target>

Get the current value of the state. If this is a signal, this will subscribe the current scope to the signal. If the value has been dropped, this will panic. Calling this on a Signal is the same as using the signal() syntax to read and subscribe to its value

fn try_read( &self ) -> Result<<Self::Storage as AnyStorage>::Ref<'_, Self::Target>, BorrowError>

Try to get the current value of the state. If this is a signal, this will subscribe the current scope to the signal.

fn read_unchecked( &self ) -> <Self::Storage as AnyStorage>::Ref<'static, Self::Target>

Get a reference to the value without checking the lifetime. This will subscribe the current scope to the signal.

fn peek(&self) -> <Self::Storage as AnyStorage>::Ref<'_, Self::Target>

Get the current value of the state without subscribing to updates. If the value has been dropped, this will panic.

fn try_peek( &self ) -> Result<<Self::Storage as AnyStorage>::Ref<'_, Self::Target>, BorrowError>

Try to peek the current value of the signal without subscribing to updates. If the value has been dropped, this will return an error.

fn peek_unchecked( &self ) -> <Self::Storage as AnyStorage>::Ref<'static, Self::Target>

Get the current value of the signal without checking the lifetime. Unlike read, this will not subscribe the current scope to the signal which can cause parts of your UI to not update.

fn with<O>(&self, f: impl FnOnce(&Self::Target) -> O) -> O

Run a function with a reference to the value. If the value has been dropped, this will panic.

fn with_peek<O>(&self, f: impl FnOnce(&Self::Target) -> O) -> O

Run a function with a reference to the value. If the value has been dropped, this will panic.

fn index<I>( &self, index: I ) -> <Self::Storage as AnyStorage>::Ref<'_, <Self::Target as Index<I>>::Output>

where Self::Target: Index<I>,

Index into the inner value and return a reference to the result. If the value has been dropped or the index is invalid, this will panic.

impl<T, S> Sub<T> for Signal<T, S>

where T: Sub<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

type Output = T

The resulting type after applying the - operator.

fn sub(self, rhs: T) -> <Signal<T, S> as Sub<T>>::Output

Performs the - operation.

impl<T, S> SubAssign<T> for Signal<T, S>

where T: Sub<Output = T> + Copy + 'static, S: Storage<SignalData<T>>,

fn sub_assign(&mut self, rhs: T)

Performs the -= operation.

impl<T, S> Writable for Signal<T, S>

where T: 'static, S: Storage<SignalData<T>>,

type Mut<'a, R: 'static + ?Sized> = Write<'a, R, S>

The type of the reference.

fn map_mut<I, U, F>( ref_: <Signal<T, S> as Writable>::Mut<'_, I>, f: F ) -> <Signal<T, S> as Writable>::Mut<'_, U>

where U: 'static + ?Sized, F: FnOnce(&mut I) -> &mut U, I: ?Sized,

Map the reference to a new type.

fn try_map_mut<I, U, F>( ref_: <Signal<T, S> as Writable>::Mut<'_, I>, f: F ) -> Option<<Signal<T, S> as Writable>::Mut<'_, U>>

where I: 'static + ?Sized, U: 'static + ?Sized, F: FnOnce(&mut I) -> Option<&mut U>,

Try to map the reference to a new type.

fn downcast_lifetime_mut<'a, 'b, R>( mut_: <Signal<T, S> as Writable>::Mut<'a, R> ) -> <Signal<T, S> as Writable>::Mut<'b, R>

where 'a: 'b, R: 'static + ?Sized,

Downcast a mutable reference in a RefMut to a more specific lifetime

fn try_write_unchecked( &self ) -> Result<<Signal<T, S> as Writable>::Mut<'static, <Signal<T, S> as Readable>::Target>, BorrowMutError>

Try to get a mutable reference to the value without checking the lifetime. This will update any subscribers.

fn write(&mut self) -> Self::Mut<'_, Self::Target>

Get a mutable reference to the value. If the value has been dropped, this will panic.

fn try_write(&mut self) -> Result<Self::Mut<'_, Self::Target>, BorrowMutError>

Try to get a mutable reference to the value.

fn write_unchecked(&self) -> Self::Mut<'static, Self::Target>

Get a mutable reference to the value without checking the lifetime. This will update any subscribers.

fn with_mut<O>(&mut self, f: impl FnOnce(&mut Self::Target) -> O) -> O

Run a function with a mutable reference to the value. If the value has been dropped, this will panic.

fn index_mut<I>( &mut self, index: I ) -> Self::Mut<'_, <Self::Target as Index<I>>::Output>

where Self::Target: IndexMut<I>,

Index into the inner value and return a reference to the result.

impl<T, S> Copy for Signal<T, S>

where T: 'static, S: Storage<SignalData<T>>,

impl<T, S> Eq for Signal<T, S>

where T: 'static, S: Storage<SignalData<T>>,