Home

Awesome

<!-- cargo-rdme start -->

Leptos Query

<p align="center"> <a href="https://github.com/gaucho-labs/leptos-query"> <img src="https://raw.githubusercontent.com/gaucho-labs/leptos-query/main/logo.svg" alt="Leptos Query" width="150"/> </a> </p>

<img alt="github" src="https://img.shields.io/badge/github-gaucho--labs/leptos--query-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20"> <img alt="crates.io" src="https://img.shields.io/crates/v/leptos_query.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20"> <img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-leptos_query-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20"> <img alt="build status" src="https://img.shields.io/github/actions/workflow/status/gaucho-labs/leptos_query/rust.yml?branch=main&style=for-the-badge" height="20">

FAQ | Examples | Live Demo

About

Leptos Query is a async state management library for Leptos.

Heavily inspired by Tanstack Query.

Queries are useful for data fetching, caching, and synchronization with server state.

A Query provides:

The main entry points to using Queries are:

Feature Flags

Version compatibility for Leptos and Leptos Query

The table below shows the compatible versions of leptos_query for each leptos version. Ensure you are using compatible versions to avoid potential issues.

leptos versionleptos_query version
0.6.*0.5.* or 0.4.*
0.5.*0.3.*

Installation

cargo add leptos_query

Then add the relevant feature(s) to your Cargo.toml


[features]
hydrate = [
    "leptos_query/hydrate",
    # ...
]
ssr = [
    "leptos_query/ssr",
    # ...
 ]

Quick Start

If you are using SSR you may have to use supress_query_load in your server's main function. See the FAQ for more information.

In the root of your App, provide a query client with [provide_query_client] or [provide_query_client_with_options] if you want to override the default options.

use leptos_query::*;
use leptos::*;

#[component]
pub fn App() -> impl IntoView {
    // Provides Query Client for entire app.
    provide_query_client();

    // Rest of App...
}

Then make a query function with [create_query][crate::create_query::create_query()]

use leptos::*;
use leptos_query::*;


// Query for a track.
fn track_query() -> QueryScope<TrackId, TrackData> {
    create_query(
        get_track,
        QueryOptions::default(),
    )
}

// Make a key type.
#[derive(Debug, Clone, Hash, Eq, PartialEq)]
struct TrackId(i32);

// The result of the query fetcher.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
struct TrackData {
   name: String,
}

// Query fetcher.
async fn get_track(id: TrackId) -> TrackData {
    todo!()
}

Now you can use the query in any component in your app.

use leptos::*;
use leptos_query::*;

#[component]
fn TrackView(id: TrackId) -> impl IntoView {
    let QueryResult {
        data,
        ..
    } = track_query().use_query(move|| id.clone());

    view! {
       <div>
           // Query data should be read inside a Transition/Suspense component.
           <Transition
               fallback=move || {
                   view! { <h2>"Loading..."</h2> }
               }>
               {move || {
                    data
                        .get()
                        .map(|track| {
                           view! { <h2>{track.name}</h2> }
                        })
               }}
           </Transition>
       </div>
    }
}

For a complete working example see the example directory

Devtools Quickstart

To use the devtools, you need to add the devtools crate:

cargo add leptos_query_devtools

Then in your cargo.toml enable the csr feature.

Hydrate Example

[features]
hydrate = [
    "leptos_query_devtools/csr",
]

CSR Example

[features]
csr = [
    "leptos_query_devtools/csr",
]

Then in your app, render the devtools component. Make sure you also provide the query client.

Devtools will by default only show in development mode. It will not be shown, or included in binary, when you build your app in release mode. If you want to override this behaviour, you can enable the force feature.


use leptos_query_devtools::LeptosQueryDevtools;
use leptos_query::*;
use leptos::*;

#[component]
fn App() -> impl IntoView {
    provide_query_client();

    view!{
        <LeptosQueryDevtools />
        // Rest of App...
    }
}

<!-- cargo-rdme end -->