Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://redux-toolkit.js.org/rtk-query/api/created-api/hooks below:

API Slices: React Hooks | Redux Toolkit

The core RTK Query createApi method is UI-agnostic, in the same way that the Redux core library and Redux Toolkit are UI-agnostic. They are all plain JS logic that can be used anywhere. So, if you import createApi from '@reduxjs/toolkit/query', it does not have any specific UI integrations included.

However, RTK Query also provides the ability to auto-generate React hooks for each of your endpoints. Since this specifically depends on React itself, RTK Query provides an additional entry point that exposes a customized version of createApi that includes that functionality:

import { createApi } from '@reduxjs/toolkit/query/react'

If you have used the React-specific version of createApi, the generated api slice structure will also contain a set of React hooks. The primary endpoint hooks are available as api.endpoints[endpointName].useQuery, api.endpoints[endpointName].useMutation, and api.endpoints[endpointName].useInfiniteQuery, matching how you defined that endpoint.

The same hooks are also added to the api object itself, and given auto-generated names based on the endpoint name and query/mutation type.

For example, if you had endpoints for getPosts and updatePost, these options would be available:

Generated React Hook names

const { data } = api.endpoints.getPosts.useQuery()
const [updatePost, { data }] = api.endpoints.updatePost.useMutation()


const { data } = api.useGetPostsQuery()
const [updatePost, { data }] = api.useUpdatePostMutation()

The general format is use(Endpointname)(Query|Mutation|InfiniteQuery) - use is prefixed, the first letter of your endpoint name is capitalized, then Query or Mutation or InfiniteQuery is appended depending on the type.

RTK Query provides additional hooks for more advanced use-cases, although not all are generated directly on the api object as well.

Most of the hooks are generated on a per-endpoint basis.

The full list of hooks generated in the React-specific version of createApi is:

• Endpoint-specific, generated the api object with a unique name and on the endpoint object with a generic name:
  • useQuery (all standard queries)
  • useMutation (all mutations)
  • useInfiniteQuery (only infinite queries)
  • useLazyQuery (all standard queries)
• Endpoint-specific, only generated on the endpoint object with a generic name:
  • useQueryState
  • useQuerySubscription
  • useLazyQuerySubscription
  • useInfiniteQueryState
  • useInfiniteQuerySubscription
• Endpoint-agnostic, generated on the api object:
  • usePrefetch

For the example above, the full set of generated hooks for the api would be like so:

Generated React Hooks

api.endpoints.getPosts.useQuery(arg, options)
api.endpoints.getPosts.useQueryState(arg, options)
api.endpoints.getPosts.useQuerySubscription(arg, options)
api.endpoints.getPosts.useLazyQuery(options)
api.endpoints.getPosts.useLazyQuerySubscription(options)


api.endpoints.getManyPosts.useInfiniteQuery(arg, options)
api.endpoints.getManyPosts.useInfiniteQueryState(arg, options)
api.endpoints.getManyPosts.useInfiniteQuerySubscription(arg, options)


api.endpoints.updatePost.useMutation(options)



api.useGetPostsQuery(arg, options)

api.useLazyGetPostsQuery(arg, options)

api.useUpdatePostMutation(arg, options)

api.useGetManyPostsInfiniteQuery(arg, options)

api.usePrefetch(endpointName, options)

The provided hooks have a degree of feature overlap in order to provide options optimized for a given situation. The table below provides a comparison of the core features for each hook.

Allows manually triggering query requests

Allows manually triggering mutation requests

Subscribes a component to keep cached data in the store

Returns request status and cached data from the store

Re-renders as request status and data become available

Accepts polling/re-fetching options to trigger automatic re-fetches

These hooks are the main methods you will use to interact with RTK Query in your React components. They encapsulate all of logic and options needed for most data fetching and update use cases.

Accessing a useQuery hook

const useQueryResult = api.endpoints.getPosts.useQuery(arg, options)

const useQueryResult = api.useGetPostsQuery(arg, options)

A React hook that automatically triggers fetches of data from an endpoint, 'subscribes' the component to the cached data, and reads the request status and cached data from the Redux store. The component will re-render as the loading status changes and the data becomes available.

The query arg is used as a cache key. Changing the query arg will tell the hook to re-fetch the data if it does not exist in the cache already, and the hook will return the data for that query arg once it's available.

This hook combines the functionality of both useQueryState and useQuerySubscription together, and is intended to be used in the majority of situations.

• Automatically triggers requests to retrieve data based on the hook argument and whether cached data exists by default
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Accepts polling/re-fetching options to trigger automatic re-fetches when the corresponding criteria is met
• Returns the latest request status and cached data from the Redux store
• Re-renders as the request status changes and data becomes available

type UseQuery = (
  arg: any | SkipToken,
  options?: UseQueryOptions,
) => UseQueryResult

type UseQueryOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
  skip?: boolean
  refetchOnMountOrArgChange?: boolean | number
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
}

type UseQueryResult<T> = {
  

  
  originalArgs?: unknown
  
  data?: T
  
  currentData?: T
  
  error?: unknown
  
  requestId?: string
  
  endpointName?: string
  
  startedTimeStamp?: number
  
  fulfilledTimeStamp?: number

  

  
  isUninitialized: boolean
  
  isLoading: boolean
  
  isFetching: boolean
  
  isSuccess: boolean
  
  isError: boolean

  
  refetch: () => QueryActionCreatorResult
}

• Parameters
  • arg: The query argument to be used in constructing the query itself, and as a cache key for the query. You can also pass in skipToken here as an alternative way of skipping the query, see skipToken
  • options: A set of options that control the fetching behavior of the hook
• Returns
  • A query result object containing the current loading state, the actual data or error returned from the API call, metadata about the request, and a function to refetch the data. Can be customized with selectFromResult

Can be passed into useQuery, useQueryState or useQuerySubscription instead of the query argument to get the same effect as if setting skip: true in the query options.

Useful for scenarios where a query should be skipped when arg is undefined and TypeScript complains about it because arg is not allowed to be passed in as undefined, such as

will error if the query argument is not allowed to be undefined

useSomeQuery(arg, { skip: !!arg })

using skipToken instead

useSomeQuery(arg ?? skipToken)

If passed directly into a query or mutation selector, that selector will always return an uninitialized state.

See also Skipping queries with TypeScript using skipToken

Accessing a useMutation hook

const useMutationResult = api.endpoints.updatePost.useMutation(options)

const useMutationResult = api.useUpdatePostMutation(options)

A React hook that lets you trigger an update request for a given endpoint, and subscribes the component to read the request status from the Redux store. The component will re-render as the loading status changes.

• Manual control over firing a request to alter data on the server or possibly invalidate the cache
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Returns the latest request status and cached data from the Redux store
• Re-renders as the request status changes and data becomes available

type UseMutation = (
  options?: UseMutationStateOptions,
) => [UseMutationTrigger, UseMutationResult | SelectedUseMutationResult]

type UseMutationStateOptions = {
  
  selectFromResult?: (result: UseMutationStateDefaultResult) => any
  
  fixedCacheKey?: string
}

type UseMutationTrigger<T> = (arg: any) => Promise<
  { data: T } | { error: BaseQueryError | SerializedError }
> & {
  requestId: string 
  abort: () => void 
  unwrap: () => Promise<T> 
  reset: () => void 
}

type UseMutationResult<T> = {
  

  
  originalArgs?: unknown
  
  data?: T
  
  error?: unknown
  
  endpointName?: string
  
  fulfilledTimeStamp?: number

  

  
  isUninitialized: boolean
  
  isLoading: boolean
  
  isSuccess: boolean
  
  isError: boolean
  
  startedTimeStamp?: number

  
  reset: () => void
}

tip

The generated UseMutation hook will cause a component to re-render by default after the trigger callback is fired, as it affects the properties of the result. If you want to call the trigger but don't care about subscribing to the result with the hook, you can use the selectFromResult option to limit the properties that the hook cares about.

Returning a completely empty object will mean that any individual mutation call will cause only one re-render at most, e.g.

selectFromResult: () => ({})

• Parameters

  • options: A set of options that control the subscription behavior of the hook:
    • selectFromResult: A callback that can be used to customize the mutation result returned as the second item in the tuple
    • fixedCacheKey: An optional string used to enable shared results across hook instances

• Returns: A tuple containing:

  • trigger: A function that triggers an update to the data based on the provided argument. The trigger function returns a promise with the properties shown above that may be used to handle the behavior of the promise
  • mutationState: A query status object containing the current loading state and metadata about the request, or the values returned by the selectFromResult option where applicable. Additionally, this object will contain
    • a reset method to reset the hook back to its original state and remove the current result from the cache
    • an originalArgs property that contains the argument passed to the last call of the trigger function.

Accessing a useQuery hook

const useQueryResult = api.endpoints.getManyPosts.useInfiniteQuery(arg, options)

const useQueryResult = api.useGetManyPostsInfiniteQuery(arg, options)

A React hook that automatically triggers fetches of data from an endpoint, 'subscribes' the component to the cached data, and reads the request status and cached data from the Redux store. The component will re-render as the loading status changes and the data becomes available. Additionally, it will cache multiple "pages" worth of responses within a single cache entry, and allows fetching more pages forwards and backwards from the current cached pages.

The query arg is used as a cache key. Changing the query arg will tell the hook to re-fetch the data if it does not exist in the cache already, and the hook will return the data for that query arg once it's available.

The data field will be a {pages: Data[], pageParams: PageParam[]} structure containing all fetched page responses and the corresponding page param values for each page. You may use this to render individual pages, combine all pages into a single infinite list, or other display logic as needed.

This hook combines the functionality of both useInfiniteQueryState and useInfiniteQuerySubscription together, and is intended to be used in the majority of situations.

As with normal query hooks, skipToken is a valid argument that will skip the query from executing.

By default, the initial request will use the initialPageParam value that was defined on the infinite query endpoint. If you want to start from a different value, you can pass initialPageParam as part of the hook options to override that initial request value.

Use the returned fetchNextPage and fetchPreviousPage methods on the hook result object to trigger fetches forwards and backwards. These will always calculate the next or previous page param based on the current cached pages and the provided getNext/PreviousPageParam callbacks defined in the endpoint.

• Automatically triggers requests to retrieve data based on the hook argument and whether cached data exists by default
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Caches multiple pages worth of responses, and provides methods to trigger more page fetches forwards and backwards
• Accepts polling/re-fetching options to trigger automatic re-fetches when the corresponding criteria is met
• Returns the latest request status and cached data from the Redux store
• Re-renders as the request status changes and data becomes available

type UseInfiniteQuery = (
  arg: any | SkipToken,
  options?: UseQueryOptions,
) => UseInfiniteQueryResult

type InfiniteData<Data, PageParam> = {
  pages: Array<Data>
  pageParams: Array<PageParam>
}

type UseInfiniteQueryOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
  skip?: boolean
  refetchOnMountOrArgChange?: boolean | number
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
  initialPageParam?: PageParam
}

type UseInfiniteQueryResult<Data, PageParam> = {
  

  
  originalArgs?: unknown
  
  data?: InfiniteData<Data, PageParam>
  
  currentData?: InfiniteData<Data, PageParam>
  
  error?: unknown
  
  requestId?: string
  
  endpointName?: string
  
  startedTimeStamp?: number
  
  fulfilledTimeStamp?: number

  

  
  isUninitialized: boolean
  
  isLoading: boolean
  
  isFetching: boolean
  
  isSuccess: boolean
  
  isError: boolean

  

  
  hasNextPage: boolean
  
  hasPreviousPage: boolean
  
  isFetchingNextPage: boolean
  
  isFetchingPreviousPage: boolean
  
  isFetchNextPageError: boolean
  
  isFetchPreviousPageError: boolean

  
  refetch: () => InfiniteQueryActionCreatorResult

  
  fetchNextPage: () => InfiniteQueryActionCreatorResult
  
  fetchPreviousPage: () => InfiniteQueryActionCreatorResult
}

• Parameters
  • arg: The query argument to be used in constructing the query itself, and as a cache key for the query. You can also pass in skipToken here as an alternative way of skipping the query, see skipToken
  • options: A set of options that control the fetching behavior of the hook
• Returns
  • A query result object containing the current loading state, the actual data or error returned from the API call, metadata about the request, and a function to refetch the data. Can be customized with selectFromResult

These hooks are useful for specific additional use cases in your application, but will probably not be used that frequently.

Accessing a useLazyQuery hook

const [trigger, result, lastPromiseInfo] =
  api.endpoints.getPosts.useLazyQuery(options)

const [trigger, result, lastPromiseInfo] = api.useLazyGetPostsQuery(options)

A React hook similar to useQuery, but with manual control over when the data fetching occurs.

This hook includes the functionality of useLazyQuerySubscription.

• Manual control over firing a request to retrieve data
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Returns the latest request status and cached data from the Redux store
• Re-renders as the request status changes and data becomes available
• Accepts polling/re-fetching options to trigger automatic re-fetches when the corresponding criteria is met and the fetch has been manually called at least once

When the trigger function returned from a LazyQuery is called, it always initiates a new request to the server even if there is cached data. Set preferCacheValue(the second argument to the function) as true if you want it to immediately return a cached value if one exists.

type UseLazyQuery = (
  options?: UseLazyQueryOptions
) => [UseLazyQueryTrigger, UseLazyQueryStateResult, UseLazyQueryLastPromiseInfo]

type UseLazyQueryOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
}

type UseLazyQueryTrigger<T> = (arg: any, preferCacheValue?: boolean) => Promise<
  QueryResultSelectorResult
> & {
  
  arg: unknown
  
  requestId: string
  
  subscriptionOptions: SubscriptionOptions

   
  abort: () => void
  
  unwrap: () => Promise<T>
  
  unsubscribe: () => void
  
  refetch: () => void
  
  updateSubscriptionOptions: (options: SubscriptionOptions) () => void
}

type UseLazyQueryStateResult<T> = {
  

  
  originalArgs?: unknown
  
  data?: T
  
  currentData?: T
  
  error?: unknown
  
  requestId?: string
  
  endpointName?: string
  
  startedTimeStamp?: number
  
  fulfilledTimeStamp?: number

  

  
  isUninitialized: boolean
  
  isLoading: boolean
  
  isFetching: boolean
  
  isSuccess: boolean
  
  isError: boolean
}

type UseLazyQueryLastPromiseInfo = {
  lastArg: any
}

• Parameters

  • options: A set of options that control the fetching behavior and returned result value of the hook. Options affecting fetching behavior will only have an effect after the lazy query has been triggered at least once.

• Returns: A tuple containing:

  • trigger: A function that fetches the corresponding data for the endpoint when called
  • result: A query result object containing the current loading state, the actual data or error returned from the API call and metadata about the request. Can be customized with selectFromResult
  • lastPromiseInfo: An object containing the last argument used to call the trigger function

Accessing a usePrefetch hook

const prefetchCallback = api.usePrefetch(endpointName, options)

A React hook which can be used to initiate fetching data ahead of time.

• Manual control over firing a request to retrieve data

type UsePrefetch = (
  endpointName: string,
  options?: UsePrefetchOptions,
) => PrefetchCallback

type UsePrefetchOptions =
  | {
      
      
      ifOlderThan?: false | number
    }
  | {
      
      
      force?: boolean
    }

type PrefetchCallback = (arg: any, options?: UsePrefetchOptions) => void

• Parameters

  • endpointName: The name of the endpoint to prefetch data for
  • options: A set of options that control whether the prefetch request should occur

• Returns

  • A prefetch callback that when called, will initiate fetching the data for the provided endpoint

This hooks exist as implementation details of the primary hooks. They may be useful in rare cases, but you should generally use the primary hooks in your apps.

Accessing a useQuery hook

const useQueryStateResult = api.endpoints.getPosts.useQueryState(arg, options)

A React hook that reads the request status and cached data from the Redux store. The component will re-render as the loading status changes and the data becomes available.

Note that this hook does not trigger fetching new data. For that use-case, see useQuery or useQuerySubscription.

• Returns the latest request status and cached data from the Redux store
• Re-renders as the request status changes and data becomes available

type UseQueryState = (
  arg: any | SkipToken,
  options?: UseQueryStateOptions,
) => UseQueryStateResult | SelectedQueryStateResult

type UseQueryStateOptions = {
  skip?: boolean
  selectFromResult?: (result: UseQueryStateDefaultResult) => any
}

type UseQueryStateResult<T> = {
  

  
  originalArgs?: unknown
  
  data?: T
  
  currentData?: T
  
  error?: unknown
  
  requestId?: string
  
  endpointName?: string
  
  startedTimeStamp?: number
  
  fulfilledTimeStamp?: number

  

  
  isUninitialized: boolean
  
  isLoading: boolean
  
  isFetching: boolean
  
  isSuccess: boolean
  
  isError: boolean
}

• Parameters

  • arg: The argument passed to the query defined in the endpoint. You can also pass in skipToken here as an alternative way of skipping the selection, see skipToken
  • options: A set of options that control the return value for the hook

• Returns

  • A query result object containing the current loading state, the actual data or error returned from the API call and metadata about the request. Can be customized with selectFromResult

Accessing a useQuerySubscription hook

const { refetch } = api.endpoints.getPosts.useQuerySubscription(arg, options)

A React hook that automatically triggers fetches of data from an endpoint, and 'subscribes' the component to the cached data.

The query arg is used as a cache key. Changing the query arg will tell the hook to re-fetch the data if it does not exist in the cache already.

Note that this hook does not return a request status or cached data. For that use-case, see useQuery or useQueryState.

• Automatically triggers requests to retrieve data based on the hook argument and whether cached data exists by default
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Accepts polling/re-fetching options to trigger automatic re-fetches when the corresponding criteria is met

type UseQuerySubscription = (
  arg: any | SkipToken,
  options?: UseQuerySubscriptionOptions,
) => UseQuerySubscriptionResult

type UseQuerySubscriptionOptions = {
  skip?: boolean
  refetchOnMountOrArgChange?: boolean | number
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
}

type UseQuerySubscriptionResult = {
  refetch: () => void 
}

• Parameters

  • arg: The argument passed to the query defined in the endpoint. You can also pass in skipToken here as an alternative way of skipping the query, see skipToken
  • options: A set of options that control the fetching behavior of the hook

• Returns

  • An object containing a function to refetch the data

Accessing a useInfiniteQueryState hook

const useInfiniteQueryStateResult =
  api.endpoints.getManyPosts.useInfiniteQueryState(arg, options)

A React hook that reads the request status and cached data from the Redux store. The component will re-render as the loading status changes and the data becomes available.

Note that this hook does not trigger fetching new data. For that use-case, see useInfiniteQuery or useInfiniteQuerySubscription.

• Returns the latest request status and cached data from the Redux store
• Re-renders as the request status changes and data becomes available

Accessing a useInfiniteQuerySubscription hook

const useInfiniteQuerySubscriptionResult =
  api.endpoints.getManyPosts.useInfiniteQuerySubscription(arg, options)

A React hook that automatically triggers fetches of data from an endpoint, and 'subscribes' the component to the cached data. Additionally, it will cache multiple "pages" worth of responses within a single cache entry, and allows fetching more pages forwards and backwards from the current cached pages.

The query arg is used as a cache key. Changing the query arg will tell the hook to re-fetch the data if it does not exist in the cache already.

Note that this hook does not return a request status or cached data. For that use-case, see useInfiniteQuery or useInfiniteQueryState.

• Automatically triggers requests to retrieve data based on the hook argument and whether cached data exists by default
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Caches multiple pages worth of responses, and provides methods to trigger more page fetches forwards and backwards
• Accepts polling/re-fetching options to trigger automatic re-fetches when the corresponding criteria is met

Accessing a useLazyQuerySubscription hook

const [trigger, lastArg] =
  api.endpoints.getPosts.useLazyQuerySubscription(options)

A React hook similar to useQuerySubscription, but with manual control over when the data fetching occurs.

Note that this hook does not return a request status or cached data. For that use-case, see useLazyQuery.

• Manual control over firing a request to retrieve data
• 'Subscribes' the component to keep cached data in the store, and 'unsubscribes' when the component unmounts
• Accepts polling/re-fetching options to trigger automatic re-fetches when the corresponding criteria is met and the fetch has been manually called at least once

type UseLazyQuerySubscription = (
  options?: UseLazyQuerySubscriptionOptions,
) => [UseLazyQuerySubscriptionTrigger, LastArg]

type UseLazyQuerySubscriptionOptions = {
  pollingInterval?: number
  skipPollingIfUnfocused?: boolean
  refetchOnReconnect?: boolean
  refetchOnFocus?: boolean
}

type UseLazyQuerySubscriptionTrigger = (
  arg: any,
  preferCacheValue?: boolean,
) => void

• Parameters

  • options: A set of options that control the fetching behavior of the hook. The options will only have an effect after the lazy query has been triggered at least once.

• Returns: A tuple containing:

  • trigger: A function that fetches the corresponding data for the endpoint when called
  • lastArg: The last argument used to call the trigger function

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4