Crate leptos

About Leptos

Leptos is a full-stack framework for building web applications in Rust. You can use it to build

• single-page apps (SPAs) rendered entirely in the browser, using client-side routing and loading or mutating data via async requests to the server
• multi-page apps (MPAs) rendered on the server, managing navigation, data, and mutations via web-standard <a> and <form> tags
• progressively-enhanced single-page apps that are rendered on the server and then hydrated on the client, enhancing your <a> and <form> navigations and mutations seamlessly when WASM is available.

And you can do all three of these using the same Leptos code.

nightly Note

Most of the examples assume you’re using nightly Rust. If you’re on stable, note the following:

1. You need to enable the "stable" flag in Cargo.toml: leptos = { version = "0.0", features = ["stable"] }
2. nightly enables the function call syntax for accessing and setting signals. If you’re using stable, you’ll just call .get(), .set(), or .update() manually. Check out the counters_stable example for examples of the correct API.

Learning by Example

If you want to see what Leptos is capable of, check out the examples:

• counter is the classic counter example, showing the basics of client-side rendering and reactive DOM updates
• counter_without_macros adapts the counter example to use the builder pattern for the UI and avoids other macros, instead showing the code that Leptos generates.
• counters introduces parent-child communication via contexts, and the <For/> component for efficient keyed list updates.
• counters_stable adapts the counters example to show how to use Leptos with stable Rust.
• error_boundary shows how to use Result types to handle errors.
• parent_child shows four different ways a parent component can communicate with a child, including passing a closure, context, and more
• fetch introduces Resources, which allow you to integrate arbitrary async code like an HTTP request within your reactive code.
• router shows how to use Leptos’s nested router to enable client-side navigation and route-specific, reactive data loading.
• counter_isomorphic shows different methods of interaction with a stateful server, including server functions, server actions, forms, and server-sent events (SSE).
• todomvc shows the basics of building an isomorphic web app. Both the server and the client import the same app code from the todomvc example. The server renders the app directly to an HTML string, and the client hydrates that HTML to make it interactive. You might also want to see how we use create_effect to serialize JSON to localStorage and reactively call DOM methods on references to elements.
• hackernews and hackernews_axum integrate calls to a real external REST API, routing, server-side rendering and hydration to create a fully-functional application that works as intended even before WASM has loaded and begun to run.
• todo_app_sqlite, todo_app_sqlite_axum, and todo_app_sqlite_viz show how to build a full-stack app using server functions and database connections.
• tailwind shows how to integrate TailwindCSS with cargo-leptos.

Details on how to run each example can be found in its README.

Quick Links

Here are links to the most important sections of the docs:

• Reactivity: the leptos_reactive overview, and more details in
  • signals: create_signal, ReadSignal, and WriteSignal (and create_rw_signal and RwSignal)
  • computations: create_memo and Memo
  • async interop: create_resource and Resource for loading data using async functions, and create_action and Action to mutate data or imperatively call async functions.
  • reactions: create_effect
• Templating/Views: the view macro
• Routing: the leptos_router crate
• Server Functions: the server macro, create_action, and create_server_action

Feature Flags

• csr (Default) Client-side rendering: Generate DOM nodes in the browser
• ssr Server-side rendering: Generate an HTML string (typically on the server)
• hydrate Hydration: use this to add interactivity to an SSRed Leptos app
• stable By default, Leptos requires nightly Rust, which is what allows the ergonomics of calling signals as functions. If you need to use stable, you will need to call .get() and .set() manually.
• serde (Default) In SSR/hydrate mode, uses serde to serialize resources and send them from the server to the client.
• serde-lite In SSR/hydrate mode, uses serde-lite to serialize resources and send them from the server to the client.
• miniserde In SSR/hydrate mode, uses miniserde to serialize resources and send them from the server to the client.

Important Note: You must enable one of csr, hydrate, or ssr to tell Leptos which mode your app is operating in.

A Simple Counter

use leptos::*;

#[component]
pub fn SimpleCounter(cx: Scope, initial_value: i32) -> impl IntoView {
    // create a reactive signal with the initial value
    let (value, set_value) = create_signal(cx, initial_value);

    // create event handlers for our buttons
    // note that `value` and `set_value` are `Copy`, so it's super easy to move them into closures
    let clear = move |_| set_value.set(0);
    let decrement = move |_| set_value.update(|value| *value -= 1);
    let increment = move |_| set_value.update(|value| *value += 1);

    // this JSX is compiled to an HTML template string for performance
    view! {
        cx,
        <div>
            <button on:click=clear>"Clear"</button>
            <button on:click=decrement>"-1"</button>
            <span>"Value: " {move || value().to_string()} "!"</span>
            <button on:click=increment>"+1"</button>
        </div>
    }
}

Leptos is easy to use with Trunk (or with a simple wasm-bindgen setup):

#[component]
fn SimpleCounter(cx: Scope, initial_value: i32) -> impl IntoView {
    todo!()
}

pub fn main() {
    mount_to_body(|cx| view! { cx,  <SimpleCounter initial_value=3 /> })
}

Re-exports

• pub use leptos_config;
• pub use leptos_dom;
• pub use leptos_server;
• pub use server_fn;
• pub use server_fn::ServerFn as _;
• pub use typed_builder;

Modules

• ev
  Types for all DOM events.
• html
  Exports types for working with HTML elements.
• math
  Exports types for working with MathML elements.
• signal_prelude
  This prelude imports all signal types as well as all signal traits needed to use those types.
• ssr
  Utilities for server-side rendering HTML.
• svg
  Exports types for working with SVG elements.

Macros

• debug_warn
  Uses println!()-style formatting to log warnings to the console (in the browser) or via eprintln!() (if not in the browser), but only if it’s a debug build.
• error
  Uses println!()-style formatting to log errors to the console (in the browser) or via eprintln!() (if not in the browser).
• log
  Uses println!()-style formatting to log something to the console (in the browser) or via println!() (if not in the browser).
• template
  An optimized, cached template for client-side rendering. Follows the same syntax as the view! macro. In hydration or server-side rendering mode, behaves exactly as the view macro. In client-side rendering mode, uses a <template> node to efficiently render the element. Should only be used with a single root element.
• view
  The view macro uses RSX (like JSX, but Rust!) It follows most of the same rules as HTML, with the following differences:
• warn
  Uses println!()-style formatting to log warnings to the console (in the browser) or via eprintln!() (if not in the browser).

Structs

• Action
  An action synchronizes an imperative async call to the synchronous reactive system.
• ErrorBoundaryProps
  Props for the ErrorBoundary component.
• ErrorBoundaryPropsBuilder
  Builder for ErrorBoundaryProps instances.
• Errors
  A struct to hold all the possible errors that could be provided by child Views
• ForProps
  Props for the For component.
• ForPropsBuilder
  Builder for ForProps instances.
• Fragment
  Represents a group of views.
• HtmlElement
  Represents an HTML element.
• LeptosOptions
  This struct serves as a convenient place to store details used for configuring Leptos. It’s used in our actix, axum, and viz integrations to generate the correct path for WASM, JS, and Websockets, as well as other configuration tasks. It shares keys with cargo-leptos, to allow for easy interoperability
• Memo
  An efficient derived reactive value based on other reactive values.
• MultiAction
  An action that synchronizes multiple imperative async calls to the reactive system, tracking the progress of each one.
• NodeRef
  Contains a shared reference to a DOM node created while using the view macro to create your UI.
• ReadSignal
  The getter for a reactive signal.
• Resource
  A signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.
• ResourceId
  Unique ID assigned to a Resource.
• RuntimeId
  Unique ID assigned to a Runtime.
• RwSignal
  A signal that combines the getter and setter into one value, rather than separating them into a ReadSignal and a WriteSignal. You may prefer this its style, or it may be easier to pass around in a context or as a function argument.
• Scope
  A Each scope can have child scopes, and may in turn have a parent.
• ScopeDisposer
  Creating a Scope gives you a disposer, which can be called to dispose of that reactive scope.
• ScopeId
  Unique ID assigned to a Scope.
• ShowProps
  Props for the Show component.
• ShowPropsBuilder
  Builder for ShowProps instances.
• Signal
  A wrapper for any kind of readable reactive signal: a ReadSignal, Memo, RwSignal, or derived signal closure.
• SignalSetter
  A wrapper for any kind of settable reactive signal: a WriteSignal, RwSignal, or closure that receives a value and sets a signal depending on it.
• StoredValue
  A non-reactive wrapper for any value, which can be created with store_value.
• SuspenseContext
  Tracks Resources that are read under a suspense context, i.e., within a Suspense component.
• SuspenseProps
  Props for the Suspense component.
• SuspensePropsBuilder
  Builder for SuspenseProps instances.
• TransitionProps
  Props for the Transition component.
• TransitionPropsBuilder
  Builder for TransitionProps instances.
• WriteSignal
  The setter for a reactive signal.

Enums

• Attribute
  Represents the different possible values an attribute node could have.
• Class
  Represents the different possible values a single class on an element could have, allowing you to do fine-grained updates to single items in Element.classList.
• MaybeSignal
  A wrapper for a value that is either T or Signal<T>.
• Property
  Represents the different possible values an element property could have, allowing you to do fine-grained updates to single fields.
• SerializationError
  Describes errors that can occur while serializing and deserializing data, typically during the process of streaming Resources from the server to the client.
• ServerFnError
  Type for errors that can occur when using server functions.
• View
  A leptos view which can be mounted to the DOM.

Traits

• IntoAttribute
  Converts some type into an Attribute.
• IntoClass
  Converts some type into a Class.
• IntoProperty
  Converts some type into a Property.
• IntoSignal
  Helper trait for converting Fn() -> T closures into Signal<T>.
• IntoSignalSetter
  Helper trait for converting Fn(T) into SignalSetter<T>.
• IntoView
  Converts the value into a View.
• Serializable
  Describes an object that can be serialized to or from a supported format Currently those are JSON and Cbor
• ServerFn
  Defines a “server function.” A server function can be called from the server or the client, but the body of its code will only be run on the server, i.e., if a crate feature ssr is enabled.
• SignalDispose
  This trait allows disposing a signal before its Scope has been disposed.
• SignalGet
  This trait allows getting an owned value of the signals inner type.
• SignalGetUntracked
  Trait implemented for all signal types which you can get a value from, such as ReadSignal, Memo, etc., which allows getting the inner value without subscribing to the current scope.
• SignalSet
  This trait allows setting the value of a signal.
• SignalSetUntracked
  Trait implemented for all signal types which you can set the inner value, such as WriteSignal and RwSignal, which allows setting the inner value without causing effects which depend on the signal from being run.
• SignalStream
  This trait allows converting a signal into a async Stream.
• SignalUpdate
  This trait allows updating the inner value of a signal.
• SignalUpdateUntracked
  This trait allows updating the signals value without causing dependant effects to run.
• SignalWith
  This trait allows obtaining an immutable reference to the signal’s inner type.
• SignalWithUntracked
  This trait allows getting a reference to the signals inner value without creating a dependency on the signal.

Functions

• ErrorBoundary
  When you render a Result<_, _> in your view, in the Err case it will render nothing, and search up through the view tree for an <ErrorBoundary/>. This component lets you define a fallback that should be rendered in that error case, allowing you to handle errors within a section of the interface.
• For
  Iterates over children and displays them, keyed by the key function given.
• Show
  A component that will show its children when the when condition is true, and show the fallback when it is false, without rerendering every time the condition changes.
• Suspense
  If any Resources are read in the children of this component, it will show the fallback while they are loading. Once all are resolved, it will render the children.
• Transition
  If any Resources are read in the children of this component, it will show the fallback while they are loading. Once all are resolved, it will render the children. Unlike Suspense, this will not fall back to the fallback state if there are further changes after the initial load.
• create_action
  Creates an Action to synchronize an imperative async call to the synchronous reactive system.
• create_effect
  Effects run a certain chunk of code whenever the signals they depend on change. create_effect immediately runs the given function once, tracks its dependence on any signal values read within it, and reruns the function whenever the value of a dependency changes.
• create_isomorphic_effect
  Creates an effect; unlike effects created by create_effect, isomorphic effects will run on the server as well as the client.
• create_local_resource
  Creates a local Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.
• create_local_resource_with_initial_value
  Creates a local Resource with the given initial value, which will only generate and run a Future using the fetcher when the source changes.
• create_many_signals
  Works exactly as create_signal, but creates multiple signals at once.
• create_many_signals_mapped
  Works exactly as create_many_signals, but applies the map function to each signal pair.
• create_memo
  Creates an efficient derived reactive value based on other reactive values.
• create_multi_action
  Creates an MultiAction to synchronize an imperative async call to the synchronous reactive system.
• create_node_ref
  Creates a shared reference to a DOM node created while using the view macro to create your UI.
• create_resource
  Creates Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.
• create_resource_with_initial_value
  Creates a Resource with the given initial value, which will only generate and run a Future using the fetcher when the source changes.
• create_rw_signal
  Creates a reactive signal with the getter and setter unified in one value. You may prefer this style, or it may be easier to pass around in a context or as a function argument.
• create_selector
  Creates a conditional signal that only notifies subscribers when a change in the source signal’s value changes whether it is equal to the key value (as determined by PartialEq.)
• create_selector_with_fn
  Creates a conditional signal that only notifies subscribers when a change in the source signal’s value changes whether the given function is true.
• create_server_action
  Creates an Action that can be used to call a server function.
• create_server_multi_action
  Creates an MultiAction that can be used to call a server function.
• create_signal
  Creates a signal, the basic reactive primitive.
• create_signal_from_stream
  Creates a signal that always contains the most recent value emitted by a Stream. If the stream has not yet emitted a value since the signal was created, the signal’s value will be None.
• create_slice
  Derives a reactive slice of an RwSignal.
• document
  Returns the Document.
• event_target
  Helper function to extract Event.target from any event.
• event_target_checked
  Helper function to extract event.target.checked from an event.
• event_target_value
  Helper function to extract event.target.value from an event.
• get_configuration
  Loads LeptosOptions from a Cargo.toml with layered overrides. If an env var is specified, like LEPTOS_ENV, it will override a setting in the file. It takes in an optional path to a Cargo.toml file. If None is provided, you’ll need to set the options as environment variables or rely on the defaults. This is the preferred approach for cargo-leptos. If Some(“./Cargo.toml”) is provided, Leptos will read in the settings itself. This option currently does not allow dashes in file or folder names, as all dashes become underscores
• mount_to
  Runs the provided closure and mounts the result to the provided element.
• mount_to_body
  Runs the provided closure and mounts the result to the <body>.
• on_cleanup
  Creates a cleanup function, which will be run when a Scope is disposed.
• provide_context
  Provides a context value of type T to the current reactive Scope and all of its descendants. This can be consumed using use_context.
• queue_microtask
  Exposes the queueMicrotask method in the browser, and simply runs the given function when on the server.
• request_animation_frame
  Runs the given function between the next repaint using Window.requestAnimationFrame.
• request_animation_frame_with_handle
  Runs the given function between the next repaint using Window.requestAnimationFrame, returning a cancelable handle.
• request_idle_callback
  Queues the given function during an idle period using Window.requestIdleCallback.
• request_idle_callback_with_handle
  Queues the given function during an idle period using Window.requestIdleCallback, returning a cancelable handle.
• set_intervalDeprecated
  Repeatedly calls the given function, with a delay of the given duration between calls, returning a cancelable handle. See setInterval().
• set_interval_with_handle
  Repeatedly calls the given function, with a delay of the given duration between calls, returning a cancelable handle. See setInterval().
• set_timeout
  Executes the given function after the given duration of time has passed. setTimeout().
• set_timeout_with_handle
  Executes the given function after the given duration of time has passed, returning a cancelable handle. setTimeout().
• spawn_local
  Spawns and runs a thread-local std::future::Future in a platform-independent way.
• store_value
  Creates a non-reactive wrapper for any value by storing it within the reactive system.
• use_context
  Extracts a context value of type T from the reactive system by traversing it upwards, beginning from the current Scope and iterating through its parents, if any. The context value should have been provided elsewhere using provide_context.
• window
  Returns the Window.
• window_event_listener
  Adds an event listener to the Window.

Type Definitions

• AttributeValue
  A type for taking anything that implements IntoAttribute.
• Children
  The most common type for the children property on components, which can only be called once.
• ChildrenFn
  A type for the children property on components that can be called more than once.
• ChildrenFnMut
  A type for the children property on components that can be called more than once, but may mutate the children.

Attribute Macros

• component
  Annotates a function so that it can be used with your template as a Leptos <Component/>.
• server
  Declares that a function is a server function. This means that its body will only run on the server, i.e., when the ssr feature is enabled.

Derive Macros

• Params
  Derives a trait that parses a map of string keys and values into a typed data structure, e.g., for route params.