<!-- WARNING: keep links absolute in this file so they work on NPM too -->
vike-react-queryEnables your SSR React components to fetch data using TanStack Query.
Powered by react-streaming.
Features:
- Data is fetched at the component level (unlike +data, which fetches at the page level)
- The rest of the page is eagerly rendered while the component waits for its data (see Progressive Rendering)
- All TanStack Query niceties
- All SSR benefits
- Fallback upon loading and/or error
- Caching
You can completely stop using Vike's +data hook — or use both: +data for some pages, and vike-react-query for others.
> [!NOTE]
> If you don't use SSR (i.e. SPA/SSG with pre-rendering), then you don't need vike-react-query — you can use TanStack Query without any Vike integration.
Table of Contents
Installation
Basic usage
Example withFallback() tags
Error Handling
Settings
Usage with Telefunc
Version history
How it works
See also
1. npm install @tanstack/react-query vike-react-query
2. Extend +config.js:
``js
// pages/+config.js
import vikeReact from 'vike-react/config'
import vikeReactQuery from 'vike-react-query/config'
export default {
// ...
extends: [vikeReact, vikeReactQuery]
}
`
> [!NOTE]
> The vike-react-query extension requires vike-react.
`jsx
import { useSuspenseQuery } from '@tanstack/react-query'
const Movie = ({ id }) => {
const result = useSuspenseQuery({
queryKey: ['movie', id],
queryFn: () =>
fetch(https://brillout.github.io/star-wars/api/films/${id}.json)
.then((res) => res.json())
})
const { title } = result.data
return (
is imported from @tanstack/react-query, you need to install vike-react-query for it to work. (The useSuspenseQuery() hook requires an HTML stream integration.)
Example
See examples/query/.
withFallback()js
withFallback(Component) // Use default loading fallback (see +Loading)
withFallback(Component, Loading) // Define loading fallback
withFallback(Component, Loading, Error) // Define loading and error fallback
withFallback(Component, undefined, Error) // Define error fallback
`tsx
// Movie.tsximport { useSuspenseQuery } from '@tanstack/react-query'
import { withFallback } from 'vike-react-query'
const Movie = withFallback(
({ id }: { id: string }) => {
const result = useSuspenseQuery({
queryKey: ['movie', id],
queryFn: () =>
fetch(
https://brillout.github.io/star-wars/api/films/${id}.json)
.then((res) => res.json())
}) const { title } = result.data
return (
Title: {title}
)
},
({ id }) => Loading movie {id},
// The props retry and error are provided by vike-react-query
// Other props, such as code, are provied by the parent component
({ id, retry, error }) => (
Failed to load movie {id}
)
)
`
If you skip the
parameter, then a default loading component (provided by vike-react) is used. You can create a custom default loading component:`jsx
// pages/+Loading.jsxexport default { component: LoadingComponent }
function LoadingComponent() {
// Applies on a component-level
return
Loading...
}
`Instead of adding a loading fallback to the component, you can set a loading fallback to the page and layouts:
jsx
// pages/+Loading.jsxexport default { layout: LoadingLayout }
function LoadingLayout() {
// Applies to the page and all layouts
return
Loading...
}
`> [!NOTE]
> The
setting is optional and only relevant when using useSuspenseQuery() without withFallback() or withFallback(Component, false).
> `js
> withFallback(Component, false) // Don't set any loading fallback
> withFallback(Component, undefined) // Use default loading fallback
> `Manual
boundaryTechnically speaking:
-
withFallback() wraps the component inside a boundary.
- +Loading.layout adds a boundary to the component as well as to all components.You can also manually add a
boundary at any arbitrary position:`js
import { Suspense } from 'react'function SomePageSection() {
return (
Loading...
tagsTo set tags such as