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.

Take a look at the Leptos Book for a walkthrough of the framework. Join us on our Discord Channel to see what the community is building. Explore our Examples to see Leptos in action.

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.
• 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.
• slots shows how to use slots on components.
• spread shows how the spread syntax can be used to spread data and/or event handlers onto elements.
• 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 and todo_app_sqlite_axum show how to build a full-stack app using server functions and database connections.
• tailwind shows how to integrate TailwindCSS with trunk for CSR.

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

• nightly: On nightly Rust, enables the function-call syntax for signal getters and setters.
• csr 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
• 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.
• rkyv In SSR/hydrate mode, uses rkyv 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.
• tracing Adds additional support for tracing to components.
• default-tls Use default native TLS support. (Only applies when using server functions with a non-WASM client like a desktop app.)
• rustls Use rustls. (Only applies when using server functions with a non-WASM client like a desktop app.)
• template_macro Enables the template! macro, which offers faster DOM node creation for some use cases in csr.

Important Note: You must enable one of csr, hydrate, or ssr to tell Leptos which mode your app is operating in. You should only enable one of these per build target, i.e., you should not have both hydrate and ssr enabled for your server binary, only ssr.

A Simple Counter

use leptos::*;

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

    view! {

        <div>
            <button on:click=clear>"Clear"</button>
            <button on:click=decrement>"-1"</button>
            <span>"Value: " {move || value.get().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(initial_value: i32) -> impl IntoView {
    todo!()
}

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

Re-exports

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

Modules

• callback
  Callbacks define a standard way to store functions and closures. They are useful for component properties, because they can be used to define optional callback functions, which generic props don’t support.
• error
  Types to make it easier to handle errors in your application.
• ev
  Types for all DOM events.
• html
  Exports types for working with HTML elements.
• logging
  Utilities for simple isomorphic logging to the console or terminal.
• math
  Exports types for working with MathML elements.
• nonce
  Utilities for exporting nonces to be used for a Content Security Policy.
• oco
  This module contains the Oco (Owned Clones Once) smart pointer, which is used to store immutable references to values. This is useful for storing, for example, strings.
• 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.
• suspense
  Types that handle asynchronous data loading via <Suspense/>.
• svg
  Exports types for working with SVG elements.

Macros

• slice
  Generates a slice into a struct with a default getter and setter.
• template
  The view macro uses RSX (like JSX, but Rust!) It follows most of the same rules as HTML, with the following differences:
• update
  Provides a simpler way to use SignalUpdate::update.
• update_value
  Provides a simpler way to use StoredValue::update_value.
• view
  The view macro uses RSX (like JSX, but Rust!) It follows most of the same rules as HTML, with the following differences:
• with
  Provides a simpler way to use SignalWith::with.
• with_value
  Provides a simpler way to use StoredValue::with_value.

Structs

• Action
  An action synchronizes an imperative async call to the synchronous reactive system.
• AdditionalAttributesDeprecated
  A collection of additional HTML attributes to be applied to an element, each of which may or may not be reactive.
• AdditionalAttributesIter
  Iterator over additional HTML attributes.
• AnimatedShowProps
  Props for the AnimatedShow component.
• AwaitProps
  Props for the Await component.
• Callback
  Callbacks define a standard way to store functions and closures.
• Disposer
  Handle to dispose of a reactive node.
• Effect
  A handle to an effect, can be used to explicitly dispose of the effect.
• ErrorBoundaryProps
  Props for the ErrorBoundary component.
• Errors
  A struct to hold all the possible errors that could be provided by child Views
• ForProps
  Props for the For component.
• Fragment
  Represents a group of views.
• FragmentData
  Represents its pending <Suspense/> fragment.
• GlobalSuspenseContext
  A single, global suspense context that will be checked when resources are read. This won’t be “blocked” by lower suspense components. This is useful for e.g., holding route transitions.
• 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 and axum 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
• MaybeProp
  A wrapping type for an optional component prop, which can either be a signal or a non-reactive value, and which may or may not have a value. In other words, this is an Option<MaybeSignal<Option<T>>> that automatically flattens its getters.
• 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.
• Owner
  A reactive owner.
• PortalProps
  Props for the Portal component.
• ProviderProps
  Props for the Provider component.
• 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.
• ScopedFuture
  Allows running a future that has access to a given scope.
• Selector
  A conditional signal that only notifies subscribers when a change in the source signal’s value changes whether the given function is true.
• ShowProps
  Props for the Show component.
• 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.
• SyncCallback
  A callback type that is Send and Sync if its input type is Send and Sync. Otherwise, you can use exactly the way you use Callback.
• TextProp
  Describes a value that is either a static or a reactive string, i.e., a String, a &str, or a reactive Fn() -> String.
• TransitionProps
  Props for the Transition component.
• Trigger
  Reactive Trigger, notifies reactive code to rerun.
• ViewFn
  New-type wrapper for the a function that returns a view with From and Default traits implemented to enable optional props in for example <Show> and <Suspense>.
• WriteSignal
  The setter for a reactive signal.

Enums

• Attribute
  Represents the different possible values an attribute node could have.
• Binding
  Bind data through attributes, or behavior through event handlers, to an element. A value of any type able to provide an iterator of bindings (like a: Vec<Binding>), can be spread onto an element using the spread syntax view! { <div {..bindings} /> }.
• 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.
• EventHandlerFn
  A statically typed event handler.
• FromUtf8Error
  Error returned from Oco::try_from for unsuccessful conversion from Oco<'_, [u8]> to Oco<'_, str>.
• MaybeSignal
  A wrapper for a value that is either T or Signal<T>.
• Oco
  “Owned Clones Once” - a smart pointer that can be either a reference, an owned value, or a reference counted pointer. This is useful for storing immutable values, such as strings, in a way that is cheap to clone and pass around.
• 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.
• ServerFnErrorErr
  Type for errors that can occur when using server functions.
• View
  A leptos view which can be mounted to the DOM.

Traits

• Callable
  A wrapper trait for calling callbacks.
• CollectView
  Collects an iterator or collection into a View.
• 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>.
• IntoStyle
  Converts some type into a Style.
• 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
• SignalDispose
  This trait allows disposing a signal before its owner 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

• AnimatedShow
  A component that will show its children when the when condition is true. Additionally, you need to specify a hide_delay. If the when condition changes to false, the unmounting of the children will be delayed by the specified Duration. If you provide the optional show_class and hide_class, you can create very easy mount / unmount animations.
• Await
  Allows you to inline the data loading for an async block or server function directly into your view. This is the equivalent of combining a create_resource that only loads once (i.e., with a source signal || ()) with a Suspense with no fallback.
• 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.
• Portal
  Renders components somewhere else in the DOM.
• Provider
  Uses the context API to provide_context to its children and descendants, without overwriting any contexts of the same type in its own reactive scope.
• 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 Resource is 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.
• as_child_of_current_owner
  Wraps the given function so that, whenever it is called, it creates a child node owned by whichever reactive node was the owner when it was created, runs the function, and returns a disposer that can be used to dispose of the child later.
• batch
  Batches any reactive updates, preventing effects from running until the whole function has run. This allows you to prevent rerunning effects if multiple signal updates might cause the same effect to run.
• create_action
  Creates an Action to synchronize an imperative async call to the synchronous reactive system.
• create_blocking_resource
  Creates a “blocking” Resource. When server-side rendering is used, this resource will cause any <Suspense/> you read it under to block the initial chunk of HTML from being sent to the client. This means that if you set things like HTTP headers or <head> metadata in that <Suspense/>, that header material will be included in the server’s original response.
• create_effect
  Effects run a certain chunk of code whenever the signals they depend on change. create_effect queues the given function to run 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_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_owning_memo
  Like create_memo, create_owning_memo creates an efficient derived reactive value based on other reactive values, but with two differences:
• create_read_slice
  Takes a memoized, read-only slice of a signal. This is equivalent to the read-only half of create_slice.
• create_render_effect
  Creates an effect exactly like create_effect, but runs immediately rather than being queued until the end of the current microtask. This is mostly used inside the renderer but is available for use cases in which scheduling the effect for the next tick is not optimal.
• create_resource
  Creates a 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_runtime
  Creates a new reactive runtime and sets it as the current runtime.
• 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.
• create_trigger
  Creates a Trigger, a kind of reactive primitive.
• create_write_slice
  Creates a setter to access one slice of a signal. This is equivalent to the write-only half of create_slice.
• current_runtime
  The current reactive runtime.
• 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.
• expect_context
  Extracts a context value of type T from the reactive system by traversing it upwards, beginning from the current reactive owner and iterating through its parents, if any. The context value should have been provided elsewhere using provide_context.
• 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 the current reactive owner is disposed.
• provide_context
  Provides a context value of type T to the current reactive node and all of its descendants. This can be consumed using use_context.
• queue_microtask
  The microtask is a short function which will run after the current task has completed its work and when there is no other code waiting to be run before control of the execution context is returned to the browser’s event loop.
• 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.
• run_as_child
  Runs the given function as a child of the current Owner, once.
• set_current_runtime
  Sets the current reactive runtime.
• set_interval
  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 Future in a platform-independent way.
• spawn_local_with_current_owner
  Runs a future that has access to the provided Owner’s scope context.
• spawn_local_with_owner
  Runs a future that has access to the provided Owner’s scope context.
• store_value
  Creates a non-reactive wrapper for any value by storing it within the reactive system.
• try_batch
  Attempts to batch any reactive updates, preventing effects from running until the whole function has run. This allows you to prevent rerunning effects if multiple signal updates might cause the same effect to run.
• try_spawn_local_with_current_owner
  Runs a future that has access to the provided Owner’s scope context.
• try_spawn_local_with_owner
  Runs a future that has access to the provided Owner’s scope context.
• try_with_owner
  Runs the given code with the given reactive owner.
• untrack
  Suspends reactive tracking while running the given function.
• use_context
  Extracts a context value of type T from the reactive system by traversing it upwards, beginning from the current reactive owner and iterating through its parents, if any. The context value should have been provided elsewhere using provide_context.
• watch
  A version of create_effect that listens to any dependency that is accessed inside deps and returns a stop handler.
• window
  Returns the Window.
• window_event_listener
  Creates a window event listener from a typed event, returning a cancelable handle.
• window_event_listener_untyped
  Adds an event listener to the Window, typed as a generic Event, returning a cancelable handle.
• with_current_owner
  Wraps the given function so that, whenever it is called, it is run in the reactive scope of whatever the reactive owner was when it was created.
• with_owner
  Runs the given code with the given reactive owner.

Type Aliases

• 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/>.
• island
  Defines a component as an interactive island when you are using the experimental-islands feature of Leptos. Apart from the macro name, the API is the same as the component macro.
• 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 on this crate is enabled.
• slot
  Annotates a struct so that it can be used with your Component as a slot.

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.