296 | )
297 | }
298 | ```
299 |
300 | ### Query Keys
301 |
302 | Since React Query uses a query's **unique key** for essentially everything, it's important to tailor them so that will change with your query requirements. In other libraries like Zeit's SWR, you'll see the use of URL's and GraphQL query template strings to achieve this, but we believe at scale, this becomes prone to typos and errors. To relieve this issue, you can pass a **tuple key** with a `string` and `object` of variables to deterministically get the the same key.
303 |
304 | > Pro Tip: Variables passed in the key are automatically passed to your query function!
305 |
306 | All of the following queries would result in using the same key:
307 |
308 | ```js
309 | useQuery(['todos', { status, page }])
310 | useQuery(['todos', { page, status }])
311 | useQuery(['todos', { page, status, other: undefined }])
312 | ```
313 |
314 | ### Query Variables
315 |
316 | To use external props, state, or variables in a query function, pass them as a variables in your query key! They will be passed through to your query function as the first parameter.
317 |
318 | ```js
319 | function Todos({ status }) {
320 | const { data, isLoading, error } = useQuery(
321 | ['todos', { status, page }],
322 | fetchTodoList // This is the same as `fetchTodoList({ status, page })`
323 | )
324 | }
325 | ```
326 |
327 | Whenever a query's key changes, the query will automatically update:
328 |
329 | ```js
330 | function Todos() {
331 | const [page, setPage] = useState(0)
332 |
333 | const { data, isLoading, error } = useQuery(
334 | ['todos', { page }],
335 | fetchTodoList
336 | )
337 |
338 | const onNextPage = () => {
339 | setPage(page => page + 1)
340 | }
341 |
342 | return (
343 | <>
344 | {/* ... */}
345 |
346 |
347 | )
348 | }
349 | ```
350 |
351 | ### Dependent Queries
352 |
353 | React Query makes it easy to make queries that depend on other queries for both:
354 |
355 | - Parallel Queries (avoiding waterfalls) and
356 | - Serial Queries (when a piece of data is required for the next query to happen).
357 |
358 | To do this, you can use the following 2 approaches:
359 |
360 | #### Pass a falsey query key
361 |
362 | If a query isn't ready to be requested yet, just pass a falsey value as the query key:
363 |
364 | ```js
365 | const { data: user } = useQuery(['user', { userId }])
366 | const { data: projects } = useQuery(user && ['projects', { userId: user.id }]) // User is `null`, so the query key will be falsey
367 | ```
368 |
369 | #### Use a query key function
370 |
371 | If a function is passed, the query will not execute until the function can be called without throwing:
372 |
373 | ```js
374 | const { data: user } = useQuery(['user', { userId }])
375 | const { data: projects } = useQuery(() => ['projects', { userId: user.id }]) // This will throw until `user` is available
376 | ```
377 |
378 | #### Mix them together!
379 |
380 | ```js
381 | const [ready, setReady] = React.useState(false)
382 | const { data: user } = useQuery(ready && ['user', { userId }]) // Wait for ready to be truthy
383 | const { data: projects } = useQuery(
384 | () => ['projects', { userId: user.id }] // Wait for user.id to become available (and not throw)
385 | ```
386 |
387 | ### Caching & Invalidation
388 |
389 | React Query caching is automatic out of the box. It uses a `stale-while-revalidate` in-memory caching strategy together with robust query deduping to always ensure a query's data is only cached when it's needed and only cached once even if that query is used multiple times across your application.
390 |
391 | At a glance:
392 |
393 | - The cache is keyed on unique `query + variables` combinations.
394 | - By default query results become **stale** immediately after a successful fetch. This can be configured using the `staleTime` option at both the global and query-level.
395 | - Stale queries are automatically refetched whenever their **query keys change (this includes variables used in query key tuples)** or when **new usages/instances** of a query are mounted.
396 | - By default query results are **always** cached **when in use**.
397 | - If and when a query is no longer being used, it becomes **inactive** and by default is cached in the background for **5 minutes**. This time can be configured using the `cacheTime` option at both the global and query-level.
398 | - After a query is inactive for the `cacheTime` specified (defaults to 5 minutes), the query is deleted and garbage collected.
399 |
400 |
401 | A more detailed example of the caching lifecycle
402 |
403 | Let's assume we are using the default `cacheTime` of **5 minutes** and the default `staleTime` of `0`.
404 |
405 | - A new instance of `useQuery('todos', fetchTodos)` mounts.
406 | - Since no other queries have been made with this query + variable combination, this query will show a hard loading state and make a network request to fetch the data.
407 | - It will then cache the data using `'todos'` and `` as the unique identifiers for that cache.
408 | - A stale invalidation is scheduled using the `staleTime` option as a delay (defaults to `0`, or immediately).
409 | - A second instance of `useQuery('todos', fetchTodos)` mounts elsewhere.
410 | - Because this exact data exist in the cache from the first instance of this query, that data is immediately returned from the cache.
411 | - Since the query is stale, it is refetched in the background automatically.
412 | - Both instances of the `useQuery('todos', fetchTodos)` query are unmount and no longer in use.
413 | - Since there are no more active instances to this query, a cache timeout is set using `cacheTime` to delete and garbage collect the query (defaults to **5 minutes**).
414 | - No more instances of `useQuery('todos', fetchTodos)` appear within **5 minutes**.
415 | - This query and its data is deleted and garbage collected.
416 |
417 |
418 |
419 | ### Load-More & Infinite-Scroll Pagination
420 |
421 | Rendering paginated lists that can "load more" data or "infinite scroll" is a common UI pattern. React Query supports some useful features for querying these types of lists. Let's assume we have an API that returns pages of `todos` 3 at a time based on a `cursor` index:
422 |
423 | ```js
424 | fetch('/api/projects?cursor=0')
425 | // { data: [...], nextId: 3}
426 | fetch('/api/projects?cursor=3')
427 | // { data: [...], nextId: 6}
428 | fetch('/api/projects?cursor=6')
429 | // { data: [...], nextId: 9}
430 | ```
431 |
432 | Using the `nextId` value in each page's response, we can configure `useQuery` to fetch more pages as needed:
433 |
434 | - Configure your query function to use optional pagination variables. We'll send through the `nextId` as the `cursor` for the next page request.
435 | - Set the `paginated` option to `true`.
436 | - Define a `getCanFetchMore` option to know if there is more data to load (it receives the `lastPage` and `allPages` as parameters).
437 |
438 | ```js
439 | import { useQuery } from 'react-query'
440 |
441 | function Todos() {
442 | const {
443 | data: pages,
444 | isLoading,
445 | isFetching,
446 | isFetchingMore,
447 | fetchMore,
448 | canFetchMore,
449 | } = useQuery(
450 | 'todos',
451 | ({ nextId } = {}) => fetch('/api/projects?cursor=' + (nextId || 0)),
452 | {
453 | paginated: true,
454 | getCanFetchMore: (lastPage, allPages) => lastPage.nextId,
455 | }
456 | )
457 |
458 | // ...
459 | }
460 | ```
461 |
462 | You'll notice a few new things now:
463 |
464 | - `data` is now an array of pages that contain query results, instead of the query results themselves
465 | - A `fetchMore` function is now available
466 | - A `canFetchMore` boolean is now available
467 | - An `isFetchingMore` boolean is now available
468 |
469 | These can now be used to render a "load more" list (this example uses an `offset` key):
470 |
471 | ```js
472 | import { useQuery } from 'react-query'
473 |
474 | function Todos() {
475 | const {
476 | data: pages,
477 | isLoading,
478 | isFetching,
479 | isFetchingMore,
480 | fetchMore,
481 | canFetchMore,
482 | } = useQuery(
483 | 'projects',
484 | ({ offset } = {}) => fetch('/api/projects?offset=' + (offset || 0)),
485 | {
486 | paginated: true,
487 | getCanFetchMore: (lastPage, allPages) => lastPage.nextId,
488 | }
489 | )
490 |
491 | const loadMore = async () => {
492 | try {
493 | // Get the last page
494 | const lastPage = pages[pages.length - 1]
495 | const { nextId } = lastPage
496 | // Fetch more starting from nextId
497 | await fetchMore({
498 | offset: nextId,
499 | })
500 | } catch {}
501 | }
502 |
503 | return isLoading ? (
504 |
526 |
527 | ) : null
528 | }
529 | ```
530 |
531 | #### What happens when a paginated query needs to be refetched?\*\*
532 |
533 | When a paginated query becomes `stale` and needs to be refetched, each page is fetched `individually` with the same variables that were used to request it originally. If a paginated query's results are ever removed from the cache, the pagination restarts at the initial state with a single page being requested.
534 |
535 | ### Scroll Restoration
536 |
537 | Out of the box, "scroll restoration" Just Works™️ in React Query. The reason for this is that query results are cached and retrieved synchronously when rendered. As long as a query is cached and has not been garbage collected, you should never experience problems with scroll restoration.
538 |
539 | ### Manual Querying
540 |
541 | If you ever want to disable a query from automatically running, you can use the `manual = true` option. When `manual` is set to true:
542 |
543 | - The query will not automatically refetch due to changes to their query function or variables.
544 | - The query will not automatically refetch due to `refetchQueries` options in other queries or via `refetchQuery` calls.
545 |
546 | ```js
547 | function Todos() {
548 | const { data, isLoading, error, refetch, isFetching } = useQuery(
549 | 'todos',
550 | fetchTodoList,
551 | {
552 | manual: true,
553 | }
554 | )
555 |
556 | return (
557 | <>
558 |
559 |
560 | {isLoading ? (
561 | Loading...
562 | ) : error ? (
563 | Error: {error.message}
564 | ) : data ? (
565 | <>
566 |
567 | {data.map(todo => (
568 |
{todo.title}
569 | ))}
570 |
571 |
572 | ) : null}
573 |
574 | )
575 | }
576 | ```
577 |
578 | > Pro Tip: Don't use `manual` for dependent queries. Use [Dependent Queries](#dependent-queries) instead!
579 |
580 | ### Retries
581 |
582 | When a `useQuery` query fails (the function throws an error), React Query will automatically retry the query if that query's request has not reached the max number of consecutive retries (defaults to `3`).
583 |
584 | You can configure retries both on a global level and an individual query level.
585 |
586 | - Setting `retry = false` will disable retries.
587 | - Setting `retry = 6` will retry failing requests 6 times before showing the final error thrown by the function.
588 | - Setting `retry = true` will infinitely retry failing requests.
589 |
590 | ```js
591 | import { useQuery } from 'react-query'
592 |
593 | // Make specific query retry a certain number of times
594 | const { data, isLoading, error } = useQuery(
595 | ['todos', { page: 1 }],
596 | fetchTodoList,
597 | {
598 | retry: 10, // Will retry failed requests 10 times before displaying an error
599 | }
600 | )
601 | ```
602 |
603 | ### Retry Delay
604 |
605 | By default, retries in React Query do not happen immediately after a request fails. As is standard, a back-off delay is gradually applied to each retry attempt.
606 |
607 | The default `retryDelay` is set to double (starting at `1000`ms) with each attempt, but not exceed 30 seconds:
608 |
609 | ```js
610 | // Configure for all queries
611 | import { ReactQueryConfigProvider } from 'react-query'
612 |
613 | const queryConfig = {
614 | retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
615 | }
616 |
617 | function App() {
618 | return (
619 |
620 | ...
621 |
622 | )
623 | }
624 | ```
625 |
626 | Though it is not recommended, you can obviously override the `retryDelay` function/integer in both the Provider and individual query options. If set to an integer instead of a function the delay will always be the same amount of time:
627 |
628 | ```js
629 | const { data, isLoading, error } = useQuery('todos', fetchTodoList, {
630 | retryDelay: 10000, // Will always wait 1000ms to retry, regardless of how many retries
631 | })
632 | ```
633 |
634 | ### Prefetching
635 |
636 | If you're lucky enough, you may know enough about what your users will do to be able to prefetch the data they need before it's needed! If this is the case, then you're in luck. You can use the `prefetchQuery` function to prefetch the results of a query to be placed into the cache:
637 |
638 | ```js
639 | import { prefetchQuery } from 'react-query'
640 |
641 | const prefetchTodos = async () => {
642 | const queryData = await prefetchQuery('todos', () => fetch('/todos'))
643 | // The results of this query will be cached like a normal query
644 | }
645 | ```
646 |
647 | The next time a `useQuery` instance is used for a prefetched query, it will use the cached data! If no instances of `useQuery` appear for a prefetched query, it will be deleted and garbage collected after the time specified in `cacheTime`.
648 |
649 | ### SSR & Initial Data
650 |
651 | When using SSR (server-side-rendering) with React Query there are a few things to note:
652 |
653 | - Caching is not performed during SSR. This is outside of the scope of React Query and easily leads to out-of-sync data when used with frameworks like Next.js or other SSR strategies.
654 | - Queries rendered on the server will by default use the initial state of an unfetched query. This means that `data` will be set to `null`. To get around this in SSR, you can pre-seed a query's data using the `config.initialData` option:
655 |
656 | ```js
657 | const { data, isLoading, error } = useQuery('todos', fetchTodoList, {
658 | initialData: [{ id: 0, name: 'Implement SSR!' }],
659 | })
660 |
661 | // data === [{ id: 0, name: 'Implement SSR!'}]
662 | ```
663 |
664 | The query's state will still reflect that it is stale and has not been fetched yet, and once mounted, will continue as normal and request a fresh copy of the query result.
665 |
666 | ### Suspense Mode
667 |
668 | React Query can also be used with React's new Suspense for Data Fetching API's. To enable this mode, you can set either the global or query level config's `suspense` option to `true`.
669 |
670 | Global configuration:
671 |
672 | ```js
673 | // Configure for all queries
674 | import { ReactQueryConfigProvider } from 'react-query'
675 |
676 | const queryConfig = {
677 | suspense: true,
678 | }
679 |
680 | function App() {
681 | return (
682 |
683 | ...
684 |
685 | )
686 | }
687 | ```
688 |
689 | Query configuration:
690 |
691 | ```js
692 | const { useQuery } from 'react-query'
693 |
694 | // Enable for an individual query
695 | useQuery(queryKey, queryFn, { suspense: true })
696 | ```
697 |
698 | When using suspense mode, `isLoading` and `error` states will be replaced by usage of the `React.Suspense` component (including the use of the `fallback` prop and React error boundaries for catching errors). Please see the [Suspense Example](https://codesandbox.io/s/github/tannerlinsley/react-query/tree/master/examples/sandbox) for more information on how to set up suspense mode.
699 |
700 | ### Fetch-on-render vs Fetch-as-you-render
701 |
702 | Out of the box, React Query in `suspense` mode works really well as a **Fetch-on-render** solution with no additional configuration. However, if you want to take it to the next level and implement a `Fetch-as-you-render` model, we recommend implementing [Prefetching](#prefetching) on routing and/or user interactions events to initialize queries before they are needed.
703 |
704 | ### Cancelling Query Requests
705 |
706 | By default, queries that become inactive before their promises are resolved are simply ignored instead of cancelled. Why is this?
707 |
708 | - For most applications, ignoring out-of-date queries is sufficient.
709 | - Cancellation APIs may not be available for every query function.
710 | - If cancellation APIs are available, they typically vary in implementation between utilities/libraries (eg. Fetch vs Axios vs XMLHttpRequest).
711 |
712 | But don't worry! If your queries are high-bandwidth or potentially very expensive to download, React Query exposes a generic way to **cancel** query requests using a cancellation token or other related API. To integrate with this feature, attach a `cancel` function to the promise returned by your query that implements your request cancellation. When a query becomes out-of-date or inactive, this `promise.cancel` function will be called (if available):
713 |
714 | Using `axios`:
715 |
716 | ```js
717 | import { CancelToken } from 'axios'
718 |
719 | const query = useQuery('todos', () => {
720 | // Create a new CancelToken source for this request
721 | const source = CancelToken.source()
722 |
723 | const promise = axios.get('/todos', {
724 | // Pass the source token to your request
725 | cancelToken: source.token,
726 | })
727 |
728 | // Cancel the request if React Query calls the `promise.cancel` method
729 | promise.cancel = () => {
730 | source.cancel('Query was cancelled by React Query')
731 | }
732 |
733 | return promise
734 | })
735 | ```
736 |
737 | Using `fetch`:
738 |
739 | ```js
740 | const query = useQuery('todos', () => {
741 | // Create a new AbortController instance for this request
742 | const controller = new AbortController()
743 | // Get the abortController's signal
744 | const signal = controller.signal
745 |
746 | const promise = fetch('/todos', {
747 | method: 'get',
748 | // Pass the signal to your request
749 | signal,
750 | })
751 |
752 | // Cancel the request if React Query calls the `promise.cancel` method
753 | promise.cancel = controller.abort
754 |
755 | return promise
756 | })
757 | ```
758 |
759 | ## Mutations
760 |
761 | Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, React Query exports a `useMutation` hook.
762 |
763 | ### Basic Mutations
764 |
765 | Assuming the server implements a ping mutation, that returns "pong" string, here's an example of the most basic mutation:
766 |
767 | ```js
768 | const PingPong = () => {
769 | const [mutate, { data, isLoading, error }] = useMutation(pingMutation)
770 |
771 | const onPing = async () => {
772 | try {
773 | const data = await mutate()
774 | console.log(data)
775 | // { ping: 'pong' }
776 | } catch {
777 | // Uh oh, something went wrong
778 | }
779 | }
780 | return
781 | }
782 | ```
783 |
784 | Mutations without variables are not that useful, so let's add some variables to closer match reality.
785 |
786 | ### Mutation Variables
787 |
788 | To pass `variables` to your `mutate` function, call `mutate` with an object.
789 |
790 | ```js
791 | const CreateTodo = () => {
792 | const [title, setTitle] = useState('')
793 | const [mutate] = useMutation(createTodo)
794 |
795 | const onCreateTodo = async e => {
796 | // Prevent the form from refreshing the page
797 | e.preventDefault()
798 |
799 | try {
800 | await mutate({ title })
801 | // Todo was successfully created
802 | } catch (error) {
803 | // Uh oh, something went wrong
804 | }
805 | }
806 |
807 | return (
808 |
817 | )
818 | }
819 | ```
820 |
821 | Even with just variables, mutations aren't all that special, but when used with the `refetchQueries` and `updateQuery` options, they become a very powerful tool.
822 |
823 | ### Invalidate and Refetch Queries from Mutations
824 |
825 | When a mutation succeeds, it's likely that other queries in your application need to update. Where other libraries that use normalized caches would attempt to update locale queries with the new data imperatively, React Query avoids the pitfalls that come with normalized caches and prescribes **atomic updates** instead of partial cache manipulation.
826 |
827 | For example, assume we have a mutation to post a new todo:
828 |
829 | ```js
830 | const [mutate] = useMutation(postTodo)
831 | ```
832 |
833 | When a successful `postTodo` mutation happens, we likely want all `todos` queries to get refetched to show the new todo item. To do this, you can use the `refetchQueries` option when calling a mutation's `mutate` function.
834 |
835 | ```js
836 | // When this mutation succeeds, any queries with the `todos` or `reminders` query key will be refetched
837 | const [mutate] = useMutation(addTodo, {
838 | refetchQueries: ['todos', 'reminders'],
839 | })
840 | const run = async () => {
841 | try {
842 | await mutate(todo)
843 | } catch {}
844 | }
845 |
846 | // The 3 queries below will be refetched when the mutation above succeeds
847 | const todoListQuery = useQuery('todos', fetchTodoList)
848 | const todoListQuery = useQuery(['todos', { page: 1 }], fetchTodoList)
849 | const remindersQuery = useQuery('reminders', fetchReminders)
850 | ```
851 |
852 | You can even refetch queries with specific variables by passing a query key tuple to `refetchQueries`:
853 |
854 | ```js
855 | const [mutate] = useMutation(addTodo, {
856 | refetchQueries: [['todos', { status: 'done' }]],
857 | })
858 | const run = async () => {
859 | try {
860 | await mutate(todo)
861 | } catch {}
862 | }
863 |
864 | // The query below will be refetched when the mutation above succeeds
865 | const todoListQuery = useQuery(['todos', { status: 'done' }], fetchTodoList)
866 | // However, the following query below will NOT be refetched
867 | const todoListQuery = useQuery('todos', fetchTodoList)
868 | ```
869 |
870 | If you want to **only** refetch `todos` queries that don't have variables, you can pass a tuple with `variables` set to `false`:
871 |
872 | ```js
873 | const [mutate] = useMutation(addTodo, { refetchQueries: [['todos', false]] })
874 | const run = async () => {
875 | try {
876 | await mutate(todo)
877 | } catch {}
878 | }
879 |
880 | // The query below will be refetched when the mutation above succeeds
881 | const todoListQuery = useQuery(['todos'], fetchTodoList)
882 | // However, the following query below will NOT be refetched
883 | const todoListQuery = useQuery(['todos', { status: 'done' }], fetchTodoList)
884 | ```
885 |
886 | If you prefer that the promise returned from `mutate()` only resolves **after** any `refetchQueries` have been refetched, you can pass the `waitForRefetchQueries = true` option to `mutate`:
887 |
888 | ```js
889 | const [mutate] = useMutation(addTodo, { refetchQueries: ['todos'] })
890 |
891 | const run = async () => {
892 | try {
893 | await mutate(todo, { waitForRefetchQueries: true })
894 | console.log('I will only log after all refetchQueries are done refetching!')
895 | } catch {}
896 | }
897 | ```
898 |
899 | It's important to note that `refetchQueries` by default will only happen after a successful mutation (the mutation function doesn't throw an error). If you would like to refetch the `refetchQueries` regardless of this, you can set `refetchQueriesOnFailure` to `true` in your `mutate` options:
900 |
901 | ```js
902 | const [mutate] = useMutation(addTodo, { refetchQueries: ['todos'] })
903 |
904 | const run = async () => {
905 | try {
906 | await mutate(todo, { refetchQueriesOnFailure: true })
907 | // Even if the above mutation fails, any `todos` queries will still be refetched.
908 | } catch {}
909 | }
910 | ```
911 |
912 | ### Query Updates from Mutations
913 |
914 | When dealing with mutations that **update** objects on the server, it's common for the new object to be automatically returned in the response of the mutation. Instead of invalidating any queries for that item and wasting a network call to refetch them again, we can take advantage of the object returned by the mutation function and update any query responses with that data that match that query using the `updateQuery` option:
915 |
916 | ```js
917 | const [mutate] = useMutation(editTodo)
918 |
919 | mutate(
920 | {
921 | id: 5,
922 | name: 'Do the laundry',
923 | },
924 | {
925 | updateQuery: ['todo', { id: 5 }],
926 | }
927 | )
928 |
929 | // The query below will be updated with the response from the mutation above when it succeeds
930 | const { data, isLoading, error } = useQuery(['todo', { id: 5 }], fetchTodoByID)
931 | ```
932 |
933 | ## Manually or Optimistically Setting Query Data
934 |
935 | In rare circumstances, you may want to manually update a query's response before it has been refetched. To do this, you can use the exported `setQueryData` function:
936 |
937 | ```js
938 | import { setQueryData } from 'react-query'
939 |
940 | // Full replacement
941 | setQueryData(['todo', { id: 5 }], newTodo)
942 |
943 | // or functional update
944 | setQueryData(['todo', { id: 5 }], previous => ({ ...previous, status: 'done' }))
945 | ```
946 |
947 | **Most importantly**, when manually setting a query response, it naturally becomes out-of-sync with it's original source. To ease this issue, `setQueryData` automatically triggers a background refresh of the query after it's called to ensure it eventually synchronizes with the original source.
948 |
949 | Should you choose that you do _not_ want to refetch the query automatically, you can set the `shouldRefetch` option to `false`:
950 |
951 | ```js
952 | import { setQueryData } from 'react-query'
953 |
954 | // Mutate, but do not automatically refetch the query in the background
955 | setQueryData(['todo', { id: 5 }], newTodo, {
956 | shouldRefetch: false,
957 | })
958 | ```
959 |
960 | ## Displaying Background Fetching Loading States
961 |
962 | A query's `isLoading` boolean is usually sufficient to show the initial hard-loading state for a query, but sometimes you may want to display a more subtle indicator that a query is refetching in the background. To do this, queries also supply you with an `isFetching` boolean that you can use to show that it's in a fetching state:
963 |
964 | ```js
965 | function Todos() {
966 | const { data: todos, isLoading, isFetching } = useQuery('todos', fetchTodos)
967 |
968 | return isLoading ? (
969 | Loading...
970 | ) : todos ? (
971 | <>
972 | {isFetching ?
Refreshing...
: null}
973 |
974 |
975 | {todos.map(todo => (
976 |
977 | ))}
978 |
979 |
980 | ) : null
981 | }
982 | ```
983 |
984 | ## Displaying Global Background Fetching Loading State
985 |
986 | In addition to individual query loading states, if you would like to show a global loading indicator when **any** queries are fetching (including in the background), you can use the `useIsFetching` hook:
987 |
988 | ```js
989 | import { useIsFetching } from 'react-query'
990 |
991 | function GlobalLoadingIndicator() {
992 | const isFetching = useIsFetching()
993 |
994 | return isFetching ? (
995 |
Queries are fetching in the background...
996 | ) : null
997 | }
998 | ```
999 |
1000 | ## Window-Focus Refetching
1001 |
1002 | If a user leaves your application and returns to stale data, you may want to trigger an update in the background to update any stale queries. Thankfully, **React Query does this automatically for you**, but if you choose to disable it, you can use the `ReactQueryConfigProvider`'s `refetchAllOnWindowFocus` option to disable it:
1003 |
1004 | ```js
1005 | const queryConfig = { refetchAllOnWindowFocus: false }
1006 |
1007 | function App() {
1008 | return (
1009 |
1010 | ...
1011 |
1012 | )
1013 | }
1014 | ```
1015 |
1016 | ### Custom Window Focus Event
1017 |
1018 | In rare circumstances, you may want manage your own window focus events that trigger React Query to revalidate. To do this, React Query provides a `setFocusHandler` function that supplies you the callback that should be fired when the window is focused and allows you to set up your own events. When calling `setFocusHandler`, the previously set handler is removed (which in most cases will be the defalt handler) and your new handler is used instead. For example, this is the default handler:
1019 |
1020 | ```js
1021 | setFocusHandler(handleFocus => {
1022 | // Listen to visibillitychange and focus
1023 | if (typeof window !== 'undefined' && window.addEventListener) {
1024 | window.addEventListener('visibilitychange', handleFocus, false)
1025 | window.addEventListener('focus', handleFocus, false)
1026 | }
1027 |
1028 | return () => {
1029 | // Be sure to unsubscribe if a new handler is set
1030 | window.removeEventListener('visibilitychange', handleFocus)
1031 | window.removeEventListener('focus', handleFocus)
1032 | }
1033 | })
1034 | ```
1035 |
1036 | ### Ignoring Iframe Focus Events
1037 |
1038 | A greate use-case for replacing the focus handler is that of iframe events. Iframes present problems with detecting window focus by both double-firing events and also firing false-positive events when focusing or using iframes within your app. If you experience this, you should use an event handler that ignores these events as much as possible. I recommend [this one](https://gist.github.com/tannerlinsley/1d3a2122332107fcd8c9cc379be10d88)! It can be set up in the following way:
1039 |
1040 | ```js
1041 | import { setFocusHandler } from 'react-query'
1042 | import onWindowFocus from './onWindowFocus' // The gist above
1043 |
1044 | setFocusHandler(onWindowFocus) // Boom!
1045 | ```
1046 |
1047 | ## Custom Query Key Serializers (Experimental)
1048 |
1049 | > **WARNING:** This is an advanced and experimental feature. There be dragons here. Do not change the Query Key Serializer unless you know what you are doing and are fine with encountering edge cases in the React Query API
1050 |
1051 | If you absolutely despise the default query key and variable syntax, you can replace the default query key serializer with your own by using the `ReactQueryConfigProvider` hook's `queryKeySerializerFn` option:
1052 |
1053 | ```js
1054 | const queryConfig = {
1055 | queryKeySerializerFn: userQueryKey => {
1056 | // Your custom logic here...
1057 |
1058 | return [fullQueryHash, queryGroupId, variablesHash, variables]
1059 | },
1060 | }
1061 |
1062 | function App() {
1063 | return (
1064 |
1065 | ...
1066 |
1067 | )
1068 | }
1069 | ```
1070 |
1071 | - `userQueryKey: any`
1072 | - This is the queryKey passed in `useQuery` and all other public methods and utilities exported by React Query.
1073 | - `fullQueryHash: string`
1074 | - This must be a unique `string` representing the query and variables.
1075 | - It must be stable and deterministic and should not change if things like the order of variables is changed or shuffled.
1076 | - `queryGroupId: string`
1077 | - This must be a unique `string` representing only the query type without any variables.
1078 | - It must be stable and deterministic and should not change if the variables of the query change.
1079 | - `variablesHash: string`
1080 | - This must be a unique `string` representing only the variables of the query.
1081 | - It must be stable and deterministic and should not change if things like the order of variables is changed or shuffled.
1082 | - `variables: any`
1083 | - This is the object that will be passed to the `queryFn` when using `useQuery`.
1084 |
1085 | > An additional `stableStringify` utility is also exported to help with stringifying objects to have sorted keys.
1086 |
1087 | #### URL Query Key Serializer Example
1088 |
1089 | The example below shows how to build your own serializer for use with urls and use it with React Query:
1090 |
1091 | ```js
1092 | import { ReactQueryConfigProvider, stableStringify } from 'react-query'
1093 |
1094 | function urlQueryKeySerializer(queryKey) {
1095 | // Deconstruct the url
1096 | let [url, params = ''] = queryKey.split('?')
1097 |
1098 | // Build the variables object
1099 | let variables = {}
1100 | params
1101 | .split('&')
1102 | .filter(Boolean)
1103 | .forEach(param => {
1104 | const [key, value] = param.split('=')
1105 | variables[key] = value
1106 | })
1107 |
1108 | // Use stableStringify to turn variables into a stable string
1109 | const variablesHash = Object.keys(variables).length
1110 | ? stableStringify(variables)
1111 | : ''
1112 |
1113 | // Remove trailing slashes from the url to make an ID
1114 | const queryGroupId = url.replace(/\/{1,}$/, '')
1115 |
1116 | const queryHash = `${id}_${variablesHash}`
1117 |
1118 | return [queryHash, queryGroupId, variablesHash, variables]
1119 | }
1120 |
1121 | const queryConfig = {
1122 | queryKeySerializerFn: urlQueryKeySerializer,
1123 | }
1124 |
1125 | function App() {
1126 | return (
1127 |
1128 | ...
1129 |
1130 | )
1131 | }
1132 |
1133 | // Heck, you can even make your own custom useQueryHook!
1134 |
1135 | function useUrlQuery(url, options) {
1136 | return useQuery(url, () => axios.get(url).then(res => res.data))
1137 | }
1138 |
1139 | // Use it in your app!
1140 |
1141 | function Todos() {
1142 | const todosQuery = useUrlQuery(`/todos`)
1143 | }
1144 |
1145 | function FilteredTodos({ status = 'pending' }) {
1146 | const todosQuery = useFunctionQuery([getTodos, { status }])
1147 | }
1148 |
1149 | function Todo({ id }) {
1150 | const todoQuery = useUrlQuery(`/todos/${id}`)
1151 | }
1152 |
1153 | refetchQuery('/todos')
1154 | refetchQuery('/todos?status=pending')
1155 | refetchQuery('/todos/5')
1156 | ```
1157 |
1158 | #### Function Query Key Serializer Example
1159 |
1160 | The example below shows how to you build your own functional serializer and use it with React Query:
1161 |
1162 | ```js
1163 | import { ReactQueryConfigProvider, stableStringify } from 'react-query'
1164 |
1165 | // A map to keep track of our function pointers
1166 | const functionSerializerMap = new Map()
1167 |
1168 | function functionQueryKeySerializer(queryKey) {
1169 | if (!queryKey) {
1170 | return []
1171 | }
1172 |
1173 | let queryFn = queryKey
1174 | let variables
1175 |
1176 | if (Array.isArray(queryKey)) {
1177 | queryFn = queryKey[0]
1178 | variables = queryKey[1]
1179 | }
1180 |
1181 | // Get or create an ID for the function pointer
1182 | const queryGroupId =
1183 | functionSerializerMap.get(queryFn) ||
1184 | (() => {
1185 | const id = Date.now()
1186 | functionSerializerMap.set(queryFn, id)
1187 | return id
1188 | })()
1189 |
1190 | const variablesIsObject = isObject(variables)
1191 |
1192 | const variablesHash = variablesIsObject ? stableStringify(variables) : ''
1193 |
1194 | const queryHash = `${queryGroupId}_${variablesHash}`
1195 |
1196 | return [queryHash, queryGroupId, variablesHash, variables]
1197 | }
1198 |
1199 | const queryConfig = {
1200 | queryKeySerializerFn: functionQueryKeySerializer,
1201 | }
1202 |
1203 | function App() {
1204 | return (
1205 |
1206 | ...
1207 |
1208 | )
1209 | }
1210 | // Heck, you can even make your own custom useQueryHook!
1211 |
1212 | function useFunctionQuery(functionTuple, options) {
1213 | const [queryFn, variables] = Array.isArray(functionTuple)
1214 | ? functionTuple
1215 | : [functionTuple]
1216 | return useQuery(functionTuple, queryFn, options)
1217 | }
1218 |
1219 | // Use it in your app!
1220 |
1221 | function Todos() {
1222 | const todosQuery = useFunctionQuery(getTodos)
1223 | }
1224 |
1225 | function FilteredTodos({ status = 'pending' }) {
1226 | const todosQuery = useFunctionQuery([getTodos, { status }])
1227 | }
1228 |
1229 | function Todo({ id }) {
1230 | const todoQuery = useFunctionQuery([getTodo, { id }])
1231 | }
1232 |
1233 | refetchQuery(getTodos)
1234 | refetchQuery([getTodos, { status: 'pending' }])
1235 | refetchQuery([getTodo, { id: 5 }])
1236 | ```
1237 |
1238 | # API
1239 |
1240 | ## `useQuery`
1241 |
1242 | ```js
1243 | const {
1244 | data,
1245 | error,
1246 | isFetching,
1247 | isCached,
1248 | failureCount,
1249 | isLoading,
1250 | refetch,
1251 | // with paginated mode enabled
1252 | isFetchingMore,
1253 | canFetchMore,
1254 | fetchMore,
1255 | } = useQuery(queryKey, queryFn, {
1256 | manual,
1257 | paginated,
1258 | getCanFetchMore,
1259 | retry,
1260 | retryDelay,
1261 | staleTime
1262 | cacheTime,
1263 | refetchInterval,
1264 | refetchIntervalInBackground,
1265 | refetchOnWindowFocus,
1266 | onSuccess,
1267 | onError,
1268 | suspense,
1269 | initialData
1270 | })
1271 | ```
1272 |
1273 | ### Options
1274 |
1275 | - `queryKey: String | [String, Variables: Object] | falsey | Function => queryKey`
1276 | - **Required**
1277 | - The query key to use for this query.
1278 | - If a string is passed, it will be used as the query key.
1279 | - If a `[String, Object]` tuple is passed, they will be serialized into a stable query key. See [Query Keys](#query-keys) for more information.
1280 | - If a falsey value is passed, the query will be disabled and not run automatically.
1281 | - If a function is passed, it should resolve to any other valid query key type. If the function throws, the query will be disabled and not run automatically.
1282 | - The query will automatically update when this key changes (if the key is not falsey and if `manual` is not set to `true`).
1283 | - `Variables: Object`
1284 | - If a tuple with variables is passed, this object should be **serializable**.
1285 | - Nested arrays and objects are supported.
1286 | - The order of object keys is sorted to be stable before being serialized into the query key.
1287 | - `queryFn: Function(variables) => Promise(data/error)`
1288 | - **Required**
1289 | - The function that the query will use to request data.
1290 | - Optionally receives the `variables` object passed from either the query key tuple (`useQuery(['todos', variables], queryFn)`) or the `refetch` method's `variables` option, e.g. `refetch({ variables })`.
1291 | - Must return a promise that will either resolves data or throws an error.
1292 | - `paginated: Boolean`
1293 | - Set this to `true` to enable `paginated` mode.
1294 | - In this mode, new pagination utilities are returned from `useQuery` and `data` becomes an array of page results.
1295 | - `manual: Boolean`
1296 | - Set this to `true` to disable automatic refetching when the query mounts or changes query keys.
1297 | - To refetch the query, use the `refetch` method returned from the `useQuery` instance.
1298 | - `getCanFetchMore: Function(lastPage, allPages) => Boolean`
1299 | - **Required if using `paginated` mode**
1300 | - When using `paginated` mode, this function should return `true` if there is more data that can be fetched.
1301 | - `retry: Boolean | Int`
1302 | - If `false`, failed queries will not retry by default.
1303 | - If `true`, failed queries will retry infinitely.
1304 | - If set to an `Int`, e.g. `3`, failed queries will retry until the failed query count meets that number.
1305 | - `retryDelay: Function(retryAttempt: Int) => Int`
1306 | - This function receives a `retryAttempt` integer and returns the delay to apply before the next attempt in milliseconds.
1307 | - A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff.
1308 | - A function like `attempt => attempt * 1000` applies linear backoff.
1309 | - `staleTime: Int`
1310 | - The time in milliseconds that cache data remains fresh. After a successful cache update, that cache data will become stale after this duration.
1311 | - `cacheTime: Int`
1312 | - The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration.
1313 | - `refetchInterval: false | Integer`
1314 | - Optional
1315 | - If set to a number, all queries will continuously refetch at this frequency in milliseconds
1316 | - `refetchIntervalInBackground: Boolean`
1317 | - Optional
1318 | - If set to `true`, queries that are set to continuously refetch with a `refetchInterval` will continue to refetch while their tab/window is in the background
1319 | - `refetchOnWindowFocus: Boolean`
1320 | - Optional
1321 | - Set this to `false` to disable automatic refetching on window focus (useful, when `refetchAllOnWindowFocus` is set to `true`).
1322 | - Set this to `true` to enable automatic refetching on window focus (useful, when `refetchAllOnWindowFocus` is set to `false`.
1323 | - `onError: Function(err) => void`
1324 | - Optional
1325 | - This function will fire if the query encounters an error (after all retries have happened) and will be passed the error.
1326 | - `onSuccess: Function(data) => data`
1327 | - Optional
1328 | - This function will fire any time the query successfully fetches new data.
1329 | - `suspense: Boolean`
1330 | - Optional
1331 | - Set this to `true` to enable suspense mode.
1332 | - When `true`, `useQuery` will suspend when `isLoading` would normally be `true`
1333 | - When `true`, `useQuery` will throw runtime errors when `error` would normally be truthy
1334 | - `initialData: any`
1335 | - Optional
1336 | - If set, this value will be used as the initial data for the query (as long as the query hasn't been created or cached yet)
1337 |
1338 | ### Returns
1339 |
1340 | - `data: null | Any`
1341 | - Defaults to `null`.
1342 | - The last successfully resolved data for the query.
1343 | - `error: null | Error`
1344 | - The error object for the query, if an error was thrown.
1345 | - `isLoading: Boolean`
1346 | - Will be `true` if the query is both fetching and does not have any cached data to display.
1347 | - `isFetching: Boolean`
1348 | - Will be `true` if the query is currently fetching, including background fetching.
1349 | - `isCached: Boolean`
1350 | - Will be `true` if the query's response is currently cached.
1351 | - `failureCount: Integer`
1352 | - The failure count for the query.
1353 | - Incremented every time the query fails.
1354 | - Reset to `0` when the query succeeds.
1355 | - `refetch: Function({ variables: Object, merge: Function, disableThrow: Boolean })`
1356 | - A function to manually refetch the query.
1357 | - Supports custom variables (useful for "fetch more" calls).
1358 | - Supports custom data merging (useful for "fetch more" calls).
1359 | - Set `disableThrow` to true to disable this function from throwing if an error is encountered.
1360 | - `isFetchingMore: Boolean`
1361 | - If using `paginated` mode, this will be `true` when fetching more results using the `fetchMore` function.
1362 | - `canFetchMore: Boolean`
1363 | - If using `paginated` mode, this will be `true` if there is more data to be fetched (known via the required `getCanFetchMore` option function).
1364 | - `fetchMore: Function(variables) => Promise`
1365 | - If using `paginated` mode, this function allows you to fetch the next "page" of results.
1366 | - `variables` should be an object that is passed to your query function to retrieve the next page of results.
1367 |
1368 | ## `useMutation`
1369 |
1370 | ```js
1371 | const [mutate, { data, isLoading, error }] = useMutation(mutationFn, {
1372 | refetchQueries,
1373 | refetchQueriesOnFailure,
1374 | })
1375 |
1376 | const promise = mutate(variables, { updateQuery, waitForRefetchQueries })
1377 | ```
1378 |
1379 | ### Options
1380 |
1381 | - `mutationFn: Function(variables) => Promise`
1382 | - **Required**
1383 | - A function that performs an asynchronous task and returns a promise.
1384 | - `refetchQueries: Array`
1385 | - Optional
1386 | - When the mutation succeeds, these queries will be automatically refetched.
1387 | - Must be an array of query keys, e.g. `['todos', ['todo', { id: 5 }], 'reminders']`.
1388 | - `refetchQueriesOnFailure: Boolean`
1389 | - Defaults to `false`
1390 | - Set this to `true` if you want `refetchQueries` to be refetched regardless of the mutation succeeding.
1391 | - `variables: any`
1392 | - Optional
1393 | - The variables object to pass to the `mutationFn`.
1394 | - `updateQuery: QueryKey`
1395 | - Optional
1396 | - The query key for the individual query to update with the response from this mutation.
1397 | - Suggested use is for `update` mutations that regularly return the updated data with the mutation. This saves you from making another unnecessary network call to refetch the data.
1398 | - `waitForRefetchQueries: Boolean`
1399 | - Optional
1400 | - If set to `true`, the promise returned by `mutate()` will not resolve until refetched queries are resolved as well.
1401 |
1402 | ### Returns
1403 |
1404 | - `mutate: Function(variables, { updateQuery })`
1405 | - The mutation function you can call with variables to trigger the mutation and optionally update a query with its response.
1406 | - `data: null | Any`
1407 | - Defaults to `null`
1408 | - The last successfully resolved data for the query.
1409 | - `error: null | Error`
1410 | - The error object for the query, if an error was thrown.
1411 | - `isLoading: Boolean`
1412 | - Will be `true` if the query is both fetching and does not have any cached data.
1413 | - `promise: Promise`
1414 | - The promise that is returned by the `mutationFn`.
1415 |
1416 | ## `setQueryData`
1417 |
1418 | `setQueryData` is a function for imperatively updating the response of a query. By default, this function also triggers a background refetch to ensure that the data is eventually consistent with the remote source, but this can be disabled.
1419 |
1420 | ```js
1421 | import { setQueryData } from 'react-query'
1422 |
1423 | const maybePromise = setQueryData(queryKey, data, { shouldRefetch })
1424 | ```
1425 |
1426 | ### Options
1427 |
1428 | - `queryKey: QueryKey`
1429 | - **Required**
1430 | - The query key for the individual query to update with new data.
1431 | - `data: any | Function(old) => any`
1432 | - **Required**
1433 | - Must either be the new data or a function that receives the old data and returns the new data.
1434 | - `shouldRefetch: Boolean`
1435 | - Optional
1436 | - Defaults to `true`
1437 | - Set this to `false` to disable the automatic background refetch from happening.
1438 |
1439 | ### Returns
1440 |
1441 | - `maybePromise: undefined | Promise`
1442 | - If `shouldRefetch` is `true`, a promise is returned that will either resolve when the query refetch is complete or will reject if the refetch fails (after its respective retry configurations is done).
1443 |
1444 | ## `refetchQuery`
1445 |
1446 | `refetchQuery` is a function that can be used to trigger a refetch of:
1447 |
1448 | - A group of active queries.
1449 | - A single, specific query.
1450 |
1451 | By default, `refetchQuery` will only refetch stale queries, but the `force` option can be used to include non-stale ones.
1452 |
1453 | ```js
1454 | import { refetchQuery } from 'react-query'
1455 |
1456 | const promise = refetchQuery(queryKey, { force })
1457 | ```
1458 |
1459 | ### Options
1460 |
1461 | - `queryKey: QueryKey`
1462 | - **Required**
1463 | - The query key for the query or query group to refetch.
1464 | - If a single `string` is passed, any queries using that `string` or any tuple key queries that include that `string` (e.g. passing `todos` would refetch both `todos` and `['todos', { status: 'done' }]`).
1465 | - If a tuple key is passed, only the exact query with that key will be refetched (e.g. `['todos', { status: 'done' }]` will only refetch queries with that exact key).
1466 | - If a tuple key is passed with the `variables` slot set to `false`, then only queries that match the `string` key and have no variables will be refetched (e.g. `['todos', false]` would only refetch `todos` and not `['todos', { status: 'done' }]`).
1467 | - `force: Boolean`
1468 | - Optional
1469 | - Set this to `true` to force all queries to refetch instead of only stale ones.
1470 |
1471 | ### Returns
1472 |
1473 | - `promise: Promise`
1474 | - A promise is returned that will either resolve when all refetch queries are complete or will reject if any refetch queries fail (after their respective retry configurations are done).
1475 |
1476 | ## `refetchAllQueries`
1477 |
1478 | `refetchAllQueries` is a function for imperatively triggering a refetch of all queries. By default, it will only refetch stale queries, but the `force` option can be used to refetch all queries, including non-stale ones.
1479 |
1480 | ```js
1481 | import { refetchAllQueries } from 'react-query'
1482 |
1483 | const promise = refetchAllQueries({ force, includeInactive })
1484 | ```
1485 |
1486 | ### Options
1487 |
1488 | - `force: Boolean`
1489 | - Optional
1490 | - Set this to `true` to force all queries to refetch instead of only stale ones.
1491 | - `includeInactive: Boolean`
1492 | - Optional
1493 | - Set this to `true` to also refetch inactive queries.
1494 | - Overrides the `force` option to be `true`, regardless of it's value.
1495 |
1496 | ### Returns
1497 |
1498 | - `promise: Promise`
1499 | - A promise is returned that will either resolve when all refetch queries are complete or will reject if any refetch queries fail (after their respective retry configurations are done).
1500 |
1501 | ## `useIsFetching`
1502 |
1503 | `useIsFetching` is an optional hook that returns `true` if any query in your application is loading or fetching in the background (useful for app-wide loading indicators).
1504 |
1505 | ```js
1506 | import { useIsFetching } from 'react-query'
1507 |
1508 | const isFetching = useIsFetching()
1509 | ```
1510 |
1511 | ### Returns
1512 |
1513 | - `isFetching: Boolean`
1514 | - Will be `true` if any query in your application is loading or fetching in the background.
1515 |
1516 | ## `prefetchQuery`
1517 |
1518 | `prefetchQuery` is a function that can be used to fetch and cache a query response for later before it is needed or rendered with `useQuery`. **Please note** that `prefetch` will not trigger a query fetch if the query is already cached. If you wish, you can force a prefetch for non-stale queries by using the `force` option:
1519 |
1520 | ```js
1521 | import { prefetchQuery } from 'react-query'
1522 |
1523 | const data = await prefetchQuery(queryKey, queryFn, { force, ...config })
1524 | ```
1525 |
1526 | ### Options
1527 |
1528 | The options for `prefetchQuery` are exactly the same as those of [`useQuery`](#usequery), with the exception of a `force` option:
1529 |
1530 | - `force: Boolean`
1531 | - Optional
1532 | - Set this to `true` to prefetch a query **even if it is stale**.
1533 |
1534 | ### Returns
1535 |
1536 | - `promise: Promise`
1537 | - A promise is returned that will either resolve with the **query's response data**, or throw with an **error**.
1538 |
1539 | ## `clearQueryCache`
1540 |
1541 | `clearQueryCache` does exactly what it sounds like, it clears all query caches. It does this by:
1542 |
1543 | - Immediately deleting any queries that do not have active subscriptions.
1544 | - Immediately setting `data` to `null` for all queries with active subscriptions.
1545 |
1546 | ```js
1547 | import { clearQueryCache } from 'react-query'
1548 |
1549 | clearQueryCache()
1550 | ```
1551 |
1552 | ## `ReactQueryConfigProvider`
1553 |
1554 | `ReactQueryConfigProvider` is an optional provider component and can be used to define defaults for all instances of `useQuery` within it's sub-tree:
1555 |
1556 | ```js
1557 | import { ReactQueryConfigProvider } from 'react-query'
1558 |
1559 | const queryConfig = {
1560 | retry: 3,
1561 | retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
1562 | staleTime: 0,
1563 | cacheTime: 5 * 60 * 1000,
1564 | refetchAllOnWindowFocus: true,
1565 | refetchInterval: false,
1566 | suspense: false,
1567 | }
1568 |
1569 | function App() {
1570 | return (
1571 |
1572 | ...
1573 |
1574 | )
1575 | }
1576 | ```
1577 |
1578 | ### Options
1579 |
1580 | - `config: Object`
1581 | - Must be **stable** or **memoized**. Do not create an inline object!
1582 | - For a description of all config options, please see the [`useQuery` hook](#usequery).
1583 |
--------------------------------------------------------------------------------
/examples/auto-refetching/README.md:
--------------------------------------------------------------------------------
1 | # Example
2 |
3 | To run this example:
4 |
5 | - `npm install` or `yarn`
6 | - `npm run dev` or `yarn dev`
7 |
--------------------------------------------------------------------------------
/examples/auto-refetching/components/button.js:
--------------------------------------------------------------------------------
1 | export default ({ children, ...props }) => {
2 | return
16 | }
--------------------------------------------------------------------------------
/examples/auto-refetching/libs/fetch.js:
--------------------------------------------------------------------------------
1 | import fetch from 'isomorphic-unfetch'
2 |
3 | export default async function (...args) {
4 | const res = await fetch(...args)
5 | return await res.json()
6 | }
7 |
--------------------------------------------------------------------------------
/examples/auto-refetching/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "refetch-interval",
3 | "version": "1.0.0",
4 | "main": "index.js",
5 | "license": "MIT",
6 | "dependencies": {
7 | "isomorphic-unfetch": "3.0.0",
8 | "next": "9.1.1",
9 | "react-query": "latest"
10 | },
11 | "scripts": {
12 | "dev": "next",
13 | "start": "next start",
14 | "build": "next build"
15 | }
16 | }
17 |
--------------------------------------------------------------------------------
/examples/auto-refetching/pages/api/data.js:
--------------------------------------------------------------------------------
1 | // an simple endpoint for getting current list
2 | let list = ['Item 1', 'Item 2', 'Item 3']
3 |
4 | export default (req, res) => {
5 | if (req.query.add) {
6 | if (!list.includes(req.query.add)) {
7 | list.push(req.query.add)
8 | }
9 | } else if (req.query.clear) {
10 | list = []
11 | }
12 | res.json(list)
13 | }
14 |
--------------------------------------------------------------------------------
/examples/auto-refetching/pages/index.js:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import Button from '../components/button'
3 | import fetch from '../libs/fetch'
4 |
5 | import { useQuery, useMutation } from 'react-query'
6 |
7 | export default () => {
8 | const [value, setValue] = React.useState('')
9 |
10 | const { data, isLoading } = useQuery('todos', () => fetch('/api/data'), {
11 | // Refetch the data every second
12 | refetchInterval: 1000,
13 | })
14 |
15 | const [mutateAddTodo] = useMutation(
16 | value => fetch(`/api/data?add=${value}`),
17 | {
18 | refetchQueries: ['todos'],
19 | }
20 | )
21 |
22 | const [mutateClear] = useMutation(value => fetch(`/api/data?clear=1`), {
23 | refetchQueries: ['todos'],
24 | })
25 |
26 | if (isLoading) return
174 | The "staleTime" and "cacheTime" durations have been altered in this
175 | example to show how query stale-ness and query caching work on a
176 | granular level
177 |
12 | 
4 |
5 | Hooks for fetching, caching and updating asynchronous data in React
6 |
7 |
10 |
11 | 
15 |
16 |
17 | 
21 |
22 |
23 | 
24 |
25 |
26 | 
27 |
28 |
29 | Enjoy this library? Try them all! [React Table](https://github.com/tannerlinsley/react-table), [React Form](https://github.com/tannerlinsley/react-form), [React Charts](https://github.com/tannerlinsley/react-charts)
30 |
31 | ## Quick Features
32 |
33 | - Transport, protocol & backend agnostic data fetching
34 | - Auto Caching + Refetching (stale-while-revalidate, Window Refocus, Polling/Realtime)
35 | - Parallel + Dependent Queries
36 | - Mutations + Automatic Query Refetching
37 | - Multi-layer Cache + Garbage Collection
38 | - Load-More Pagination + Scroll Recovery
39 | - Request Cancellation
40 | - [React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html) Support
41 | -
42 | 
103 |
104 | 
120 |
121 | 
137 |
138 | 
154 |
155 | 
171 |
172 | 
193 |
194 |