A lightweight React query library for efficient data fetching, caching, and synchronization.
npm install jadid-react-queryuseQuery, useMutation, useInfiniteQuery, and useManualQuery hooks, along with a QueryClientProvider to manage the state globally.
useQuery, useMutation, useInfiniteQuery, and useManualQuery hooks.
QueryClient for managing state globally across the application.
bash
npm install jadid-react-query
`
or
`bash
yarn install jadid-react-query
`
Setup
To use the hooks provided by this library, wrap your application in the QueryClientProvider component.
`js
import Example from "./components/example";
import { queryClient, QueryClientProvider } from "jadid-react-query";
export default function App() {
return (
);
}
`
`js
import { useQuery } from 'jadid-react-query';
const MyComponent = () => {
const { data, error, loading, refetch } = useQuery(
'unique-key',
'https://api.example.com/data',
{
ttl: 10000,
refetchOnWindowFocus: true,
refetchInterval: 60000,
backgroundSync: true,
}
);
if (loading) return Loading...;
if (error) return Error: {error.message};
return (
{JSON.stringify(data, null, 2)}
);
};
`
Hooks
useQuery
The useQuery hook is a powerful tool for fetching, caching, and managing server data in your React applications. It offers a variety of options for controlling the behavior of data fetching, including refetching on window focus, background synchronization, and more.
$3
`js
const { data, error, loading, refetch } = useQuery(
key: string,
url: string,
options?: UseQueryOptions
);
`
$3
- key: string
- A unique identifier for the query. This key is used to cache and retrieve data within the application. It must be unique for each query.
- url: string
- The endpoint URL from which the data is to be fetched.
- options: UseQueryOptions (optional)
- An object containing various configuration options to control the behavior of the hook.
UseQueryOptions Interface
`js
export interface UseQueryOptions {
enabled?: boolean; // Default: true
refetchOnWindowFocus?: boolean; // Default: false
refetchOnReconnect?: boolean; // Default: true
staleTime?: number; // Default: 5000 (ms)
cacheTime?: number; // Default: 10000 (ms)
refetchInterval?: number; // Default: 0 (ms)
backgroundSync?: boolean; // Default: true
retry?: number; // Default: 3
retryDelay?: number; // Default: 1000 (ms)
[key: string]: any; // Other fetch options
}
`
Usage
$3
The most basic use case involves fetching data from a given URL and displaying it in a component.
`js
import React from "react";
import { useQuery } from "your-package-name";
const MyComponent = () => {
const { data, error, loading, refetch } = useQuery(
"unique-key",
"https://api.example.com/data"
);
if (loading) return Loading...;
if (error) return Error: {error.message};
return (
{JSON.stringify(data, null, 2)}
);
};
`
$3
enabled (boolean)
- Controls whether the query is enabled. If false, the query will not automatically run. You can enable it later or trigger a manual fetch using the refetch function.
`js
const { data, refetch } = useQuery("key", "https://api.example.com", {
enabled: false
});
refetch();
`
refetchOnWindowFocus (boolean)
- If set to true, the query will refetch data whenever the window regains focus. This is useful for keeping the data up-to-date when users switch between browser tabs.
`js
useQuery("key", "https://api.example.com", {
refetchOnWindowFocus: true
});
`
staleTime (number)
- Defines how long the fetched data is considered fresh (in milliseconds). After this period, the data is considered stale and will be refetched the next time it is accessed.
`js
useQuery("key", "https://api.example.com", {
staleTime: 10000 // 10 seconds
});
`
cacheTime (number)
- Determines how long the data should be cached in memory (in milliseconds). If a query is not accessed within this time, the cached data will be garbage collected.
`js
useQuery("key", "https://api.example.com", {
cacheTime: 60000 // 1 minute
});
`
refetchInterval (number)
- Defines the interval at which the query should refetch data (in milliseconds). If set to 0, no automatic refetching will occur.
`js
useQuery("key", "https://api.example.com", {
refetchInterval: 30000 // Refetch every 30 seconds
});
`
backgroundSync (boolean)
- If true, the query will automatically refetch data when the browser comes online after being offline.
`js
useQuery("key", "https://api.example.com", {
backgroundSync: true
});
`
retry (number)
- The number of retry attempts if the fetch operation fails.
`js
useQuery("key", "https://api.example.com", {
retry: 5 // Retry up to 5 times
});
`
retryDelay (number)
- The delay between retry attempts (in milliseconds).
`js
useQuery("key", "https://api.example.com", {
retryDelay: 2000 // 2 seconds delay between retries
});
`
$3
You can pass additional fetch options (e.g., headers) through the options parameter.
`js
useQuery("key", "https://api.example.com", {
headers: {
Authorization: "Bearer my-token"
}
});
`
useMutation
The useMutation hook simplifies handling mutations (e.g., POST, PUT, DELETE) in your React apps by managing loading states, errors, and callbacks.
$3
key: Unique identifier for the mutation.
url: API endpoint.
options: Optional settings:
- onSuccess: Callback on successful mutation.
- onError: Callback on mutation failure.
- onSettled: Callback after mutation completion (success or failure).
$3
- data: Response data from the mutation.
- error: Error encountered during mutation.
- loading: Boolean indicating if the mutation is in progress.
- mutate: Function to trigger the mutation, accepting a payload.
$3
`js
const { data, error, loading, mutate } = useMutation(
"createUser",
"/api/users",
{
onSuccess: (data) => console.log("Success:", data),
onError: (error) => console.error("Error:", error),
}
);
const handleSubmit = (user) => mutate(user);
`
$3
`js
const { data, error, loading, mutate } = useMutation(
"deleteUser",
"/api/users/123",
{
onSuccess: () => console.log("User deleted successfully"),
onError: (error) => console.error("Error deleting user:", error),
}
);
const handleDelete = () => {
mutate(null, { method: "DELETE" });
};
`
$3
`js
const { data, error, loading, mutate } = useMutation(
"updateUser",
"/api/users/123",
{
onSuccess: () => console.log("User updated successfully"),
onError: (error) => console.error("Error updating user:", error),
}
);
const handleUpdate = () => {
const updatedData = {
name: "Updated Name",
email: "updated@example.com",
};
mutate(updatedData, { method: "PUT" }); // or use method: "PATCH" for partial updates
};
`
This hook helps you easily manage API mutations with built-in support for success, error handling, and loading state management.
useInfiniteQuery
The useInfiniteQuery hook allows for paginated data fetching, supporting infinite scroll implementations.
$3
`js
import React from "react";
import { useInfiniteQuery } from "./hooks/useInfiniteQuery";
const fetchPosts = async (page: number) => {
const response = await fetch(/api/posts?page=${page});
return response.json();
};
const InfiniteScrollComponent = () => {
const { data, loading, error, loadMore, hasNextPage } = useInfiniteQuery({
queryKey: "posts",
fetchFunction: fetchPosts,
pageSize: 10,
});
return (
{data.map((post) => (
{post.title}
{post.body}
))}
{loading && Loading...
}
{error && Error loading data
}
{hasNextPage && (
)}
);
};
export default InfiniteScrollComponent;
`
useManualQuery
The useManualQuery hook is a custom React hook designed to allow manual fetching of data with built-in support for caching, error handling, and various fetch options. It's similar to useQuery, but it doesn't automatically fetch data on mount—instead, it provides a refetch function that you can call manually.
`js
import React from 'react';
import { useManualQuery } from './hooks/useManualQuery';
const fetchUserData = async () => {
const response = await fetch('/api/user');
return response.json();
};
const UserComponent = () => {
const { data, error, loading, refetch } = useManualQuery(
'user',
'/api/user',
{ enabled: false }
);
return (
{loading && Loading...
}
{error && Error loading data: {error.message}
}
{data && {data.name}}
);
};
export default UserComponent;
`
API Reference
QueryClient
The QueryClient class provides methods and properties to manage query state globally.
QueryClientProvider
A React component that provides the QueryClient to your application.
useQuery
A hook for fetching and caching data.
useMutation
A hook for handling mutations.
useInfiniteQuery
A hook for handling infinite scroll/pagination.
useManualQuery`