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.9 | v0.10 |
|---|---|
SignalT | MutSignalT |
ReadSignalT | SignalT |
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.