Migration Guide: v0.9 to v0.10

Warning: v0.10 is still currently in active development. Any content below is a work in progress and not finalised yet.

Signal types have been renamed

The writable SignalT type is now called MutSignalT, and the read-only ReadSignalT type is now called SignalT. Update imports and type annotations accordingly:

v0.9v0.10
SignalTMutSignalT
ReadSignalTSignalT

When using find-and-replace, match whole words and first rename Signal to a unique temporary name, then ReadSignal to Signal, and finally the temporary name to MutSignal. Applying the two renames directly in sequence can rename the same type twice.

create_signal() keeps its name and returns MutSignalT. Dereferencing a MutSignalT produces a read-only SignalT handle. Both handles remain Copy; MutSignal provides shared write access, not an exclusive mutable borrow. A read-only handle still observes changes made through a writable handle.

Memos and reducers now return writable signals

create_memo, create_selector, create_selector_with, and Signal::map now return MutSignalT instead of the former ReadSignalT (now SignalT). Likewise, create_reducer now returns (MutSignalT, impl Fn(Msg)) instead of (ReadSignalT, impl Fn(Msg)). Existing code that only reads these values usually needs no changes. You can now also use methods such as .set() and .update() on the returned signals.

To preserve the previous read-only API, dereference the returned signal. An explicit * is needed where a SignalT is expected by value, such as a return type, type annotation, collection element, or component prop:

// Old
let doubled: ReadSignali32 = create_memo(move || count.get() * 2);

// New
let doubled: Signali32 = *create_memo(move || count.get() * 2);

For component props that accept SignalT, make the same adjustment:

let doubled = create_memo(move || count.get() * 2);

// Old
view! { CounterDisplay(value=doubled) }

// New
view! { CounterDisplay(value=*doubled) }

Writing to a memo overrides its stored value and notifies dependents; it does not write back to its sources. The next dependency-triggered recomputation may overwrite that value:

let count = create_signal(2);
let doubled = create_memo(move || count.get() * 2);

doubled.set(100);
assert_eq!(doubled.get(), 100);
assert_eq!(count.get(), 2);

count.set(3);
assert_eq!(doubled.get(), 6);

For selectors, recomputation compares the new result against the current stored value, including any manual override. Direct writes use ordinary MutSignal notification behavior without checking the selector’s comparator. In a batch, a pending dependency-triggered recomputation can overwrite a manual write at batch completion, regardless of the order of the two writes.

For reducers, direct writes notify dependents without invoking the reducer. The next dispatch applies the reducer to the current state, including any direct writes:

let (state, dispatch) = create_reducer(0, |state, delta: i32| state + delta);
state.set(10);
dispatch(2);
assert_eq!(state.get(), 12);

Components and component props

This release contains several changes to how components and component props are used and defined.

Implicit props by default

Every component now uses inline props by default. Support for struct props has been removed. To migrate, either move all fields from your props struct to function arguments, or pass the entire struct as a single prop instead.

// Old
#[derive(Props)]
struct FooProps {
    bar: i32
}
#[component]
fn Foo(props: FooProps) - View { ... }

// Old, with inline props
#[component(inline_props)]
fn Foo(bar: i32) - View { ... }

// New
#[component]
fn Foo(bar: i32) - View { ... }

New #[prop] attributes

The behavior of #[prop] attributes on component props has changed. The previous behavior was not well documented at all and was an ad-hoc modification of the typed-builder crate.

The new behavior is intentionally kept simple and adapted to Sycamore’s use case. For more details, see the doc page on the #[component] proc-macro.

Here is a quick example of the new syntax

#[component]
fn Foo(
    // Set the default value of the prop if no explicit value is passed.
    #[prop(default = 42)] x: i32,
    // Accept anything that can be converted to a String.
    #[prop(into)] y: String,
    // Option types are optional by default.
    z: Optioni32
    // This behavior can also be disabled.
    #[prop(required)]
    w: Optioni32
) - View { ... }

Components automatically return builders

The #[component] function now transforms component functions to return a fluent-style builder instead of just the raw component function. For users of the view! macro, this shouldn’t change anything but for builder API users, this makes components much nicer to use.

// Old
#[component(implicit_props)]
fn Foo(bar: i32) - View { ... }

div().children(
    Foo(FooProps::builder().bar(123).build())
)
// New
#[component]
fn Foo(bar: i32) - View { ... }

div().children(
    Foo().bar(i32)
)

This unifies the syntax between components and built-in elements.

New syntax for attribute passthrough

The way attribute passthrough is defined for a component has changed to be more flexible for alternative rendering backends.

// Old
#[component(implicit_props)]
fn MyButton(#[prop(attributes(html, button))] attributes: Attributes) - View {
    ...
}

// New
#[component(extend_element!(html:button))]
fn MyButton(attributes: Attributes) - View {
    ...
}

Show has been removed

Use a reactive if/else expression in view! instead:

// Old
view! {
    Show(when=visible) { p { "Details" } }
}

// New
view! {
    if visible.get() {
        p { "Details" }
    }
}

The visible branch is built again when the condition becomes true. If you need to keep its DOM and state mounted, use a reactive hidden attribute instead.

Interpolated text strings

String literals used as text nodes in view! now support reactive interpolation:

view! {
    p { "Hello, {name}!" }
}

Literal braces in text nodes must now be escaped as {{ and }}, just like in format!. For example, change "{}" to "{{}}". This also applies to raw string literals, including inline CSS in style elements. String literals used as attributes or component props are unchanged.

Explicit reactive attributes and properties

The view! macro no longer automatically wraps element attribute or DOM property expressions in closures. Like component props, expressions are now passed directly. Use an explicit closure when an expression should update reactively:

// Old
view! {
    button(disabled=is_editing.get())
    progress(prop:value=progress.get()[0])
}
// New
view! {
    button(disabled=move || is_editing.get())
    progress(prop:value=move || progress.get()[0])
}

This also applies to hyphenated and quoted attributes and prop: properties passed through components, for example MyInput(data-count=move || count.get().to_string()). Without a closure, a signal read such as disabled=is_editing.get() is evaluated once and will not update, even though it still compiles. Passing a signal directly where supported (for example disabled=is_editing) continues to work.

Child expressions and the DSL’s if/match expressions still automatically track reactive dependencies. Event handlers, bindings, refs, and attribute spreads continue to be passed directly.

Event handlers are now normal methods

Instead of the bespoke on:event=... syntax for event handlers, all events should be attached using on_event=... syntax. For example:

// Old
view! {
    div(on:click=|| { ... })
}
// New
view! {
    div(on_click=|| { ... })
}

This change also makes the builder API slightly simpler to use.

// Old
div().on(event::click, || { ... })
// New
div().on_click(|| { ... })

The suspense feature is enabled by default

You can remove "suspense" from your Sycamore dependency’s feature list if you use the default features. If you set default-features = false and use Suspense or resources, keep listing "suspense" explicitly.

To keep the v0.9 default feature set without suspense, disable the defaults and explicitly enable "web" and "wasm-bindgen-interning".

The hydrate feature only controls client hydration

Server rendering emits hydration keys whether or not the hydrate feature is enabled. Enable the feature on the browser build to use hydrate or hydrate_to. To omit keys from static server-rendered content, wrap it in NoHydrate. The wrapper emits boundary comments, not an extra HTML element.

Hydration expects the server-rendered DOM to match the view

hydrate_to(App, parent) now matches the DOM in order. The mount element should contain only the server-rendered output of App. Keep template whitespace, scripts, and other markup that isn’t rendered by App outside that element. Unexpected nodes can cause a hydration mismatch. The same rule applies to hydrate(App), which uses body as the mount element.

To hydrate an entire document, have App render html with explicit head and body elements. Send !doctype html immediately before the server-rendered output, and call hydrate_to(App, document()) on the client. The hydrator skips the leading doctype and adopts html itself.

For whole-document hydration, put sycamore::web::CargoSycamoreMeta {} in the shared head view to reserve a slot for build-generated bootstrap markup. The slot is a NoHydrate range containing meta name="cargo-sycamore-bootstrap". Build tooling must insert its markup immediately after that marker, inside the range, rather than appending it elsewhere in head. The component only reserves the slot; it does not load the Wasm bundle or change where a build tool injects its markup.

Write the elements the browser would otherwise insert implicitly. For example, wrap table rows in an explicit tbody; if you write table { tr { ... } }, the browser inserts a tbody that the client view does not expect.

Static text children of textarea can be hydrated. For reactive updates, use bind_value rather than dynamic text children: an HTML parser reads hydration markers inside a textarea as literal text.

Router click delegation is document-wide

While a Router is mounted, it listens for clicks that bubble to the document. This makes links added or replaced after mount work without having to register new listeners. It also means that HistoryIntegration can handle eligible same-origin links outside the router’s view. Add rel="external" to links that should use normal browser navigation, such as links to server endpoints outside the SPA.