Skip to content
tRPC

useQueries()

On this page

The useQueries hook can be used to fetch a variable number of queries at the same time using only one hook call.

The main use case for such a hook is to be able to fetch a number of queries, usually of the same type. For example if you fetch a list of todo ids, you can then map over them in a useQueries hook calling a byId endpoint that would fetch the details of each todo.

Usage

The useQueries hook is the same as that of @tanstack/query useQueries. The only difference is that instead of passing an object with a queries array, you pass a callback function that receives a t proxy and returns an array of queries.

import { 
const trpc: CreateTRPCReactBase<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>, unknown> & DecorateRouterRecord<...>
trpc } from './utils/trpc';

const 
const Component: (props: {
    postIds: string[];
}) => React.JSX.Element
Component = (
props: {
    postIds: string[];
}
props: { postIds: string[]postIds: string[] }) => {
  const 
const postQueries: UseTRPCQueryResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>[]
postQueries = 
const trpc: CreateTRPCReactBase<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>, unknown> & DecorateRouterRecord<...>
trpc.
useQueries: <Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">[], UseTRPCQueryResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>[]>(queriesCallback: (t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<...>>) => readonly Omit<...>[], options?: {
    ...;
} | undefined) => UseTRPCQueryResult<...>[]
useQueries((
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t) =>
    
props: {
    postIds: string[];
}
props.postIds: string[]postIds.
Array<string>.map<Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">>(callbackfn: (value: string, index: number, array: string[]) => Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">, thisArg?: any): Omit<...>[]
map((id: stringid) => 
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t.
post: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    byId: QueryProcedure<{
        input: {
            id: string;
        };
        output: {
            id: string;
            title: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
post.
byId: <{
    id: string;
    title: string;
}>(input: {
    id: string;
}, opts?: Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey"> | undefined) => Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">
byId({ id: stringid })),
  );

  return <>{/* [...] */}</>;
};

Providing options to individual queries

You can also pass in any normal query options to the second parameter of any of the query calls in the array such as enabled, suspense, refetchOnWindowFocus...etc. For a complete overview of all the available options, see the tanstack useQuery documentation.

import { 
const trpc: CreateTRPCReactBase<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>, unknown> & DecorateRouterRecord<...>
trpc } from './utils/trpc';

const const Component: () => React.JSX.ElementComponent = () => {
  const [
const post: UseTRPCQueryResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
post, 
const greeting: UseTRPCQueryResult<{
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
greeting] = 
const trpc: CreateTRPCReactBase<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>, unknown> & DecorateRouterRecord<...>
trpc.
useQueries: <[Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">, Omit<UseTRPCQueryOptions<{
    message: string;
}, {
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    message: string;
}>, "queryKey">], [...]>(queriesCallback: (t: UseQueriesProcedureRecord<...>) => readonly [...], options?: {
    ...;
} | undefined) => [...]
useQueries((
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t) => [
    
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t.
post: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    byId: QueryProcedure<{
        input: {
            id: string;
        };
        output: {
            id: string;
            title: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
post.
byId: <{
    id: string;
    title: string;
}>(input: {
    id: string;
}, opts?: Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey"> | undefined) => Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">
byId({ id: stringid: '1' }, { 
enabled?: QueryBooleanOption<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}, any> | undefined
enabled: false }),
    
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t.
greeting: <{
    message: string;
}>(input: {
    text: string;
}, opts?: Omit<UseTRPCQueryOptions<{
    message: string;
}, {
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    message: string;
}>, "queryKey"> | undefined) => Omit<UseTRPCQueryOptions<{
    message: string;
}, {
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    message: string;
}>, "queryKey">
greeting({ text: stringtext: 'world' }),
  ]);

  const const onButtonClick: () => voidonButtonClick = () => {
    
const post: UseTRPCQueryResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
post.
QueryObserverBaseResult<TData = unknown, TError = Error>.refetch: (options?: RefetchOptions) => Promise<QueryObserverResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>>
refetch();
  };

  return (
    <React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
      <React.JSX.IntrinsicElements.h1: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>h1>{
const post: UseTRPCQueryResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
post.
data: {
    id: string;
    title: string;
} | undefined
data && 
const post: (TRPCHookResult & QueryObserverRefetchErrorResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>) | (TRPCHookResult & QueryObserverSuccessResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>) | (TRPCHookResult & QueryObserverPlaceholderResult<...>)
post.
data: {
    id: string;
    title: string;
}
data.title: stringtitle}</React.JSX.IntrinsicElements.h1: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>h1>
      <React.JSX.IntrinsicElements.p: React.DetailedHTMLProps<React.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>p>{
const greeting: UseTRPCQueryResult<{
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
greeting.
data: {
    message: string;
} | undefined
data?.message: string | undefinedmessage}</React.JSX.IntrinsicElements.p: React.DetailedHTMLProps<React.HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>p>
      <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button React.DOMAttributes<HTMLButtonElement>.onClick?: React.MouseEventHandler<HTMLButtonElement> | undefinedonClick={const onButtonClick: () => voidonButtonClick}>Click to fetch</React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button>
    </React.JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>
  );
};

Context

You can also pass in an optional React Query context to override the default.

const [
const post: UseTRPCQueryResult<{
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
post, 
const greeting: UseTRPCQueryResult<{
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>>
greeting] = 
const trpc: CreateTRPCReactBase<BuiltRouter<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>, unknown> & DecorateRouterRecord<...>
trpc.
useQueries: <[Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">, Omit<UseTRPCQueryOptions<{
    message: string;
}, {
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    message: string;
}>, "queryKey">], [...]>(queriesCallback: (t: UseQueriesProcedureRecord<...>) => readonly [...], options?: {
    ...;
} | undefined) => [...]
useQueries(
  (
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t) => [
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t.
post: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    byId: QueryProcedure<{
        input: {
            id: string;
        };
        output: {
            id: string;
            title: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
post.
byId: <{
    id: string;
    title: string;
}>(input: {
    id: string;
}, opts?: Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey"> | undefined) => Omit<UseTRPCQueryOptions<{
    id: string;
    title: string;
}, {
    id: string;
    title: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    id: string;
    title: string;
}>, "queryKey">
byId({ id: stringid: '1' }), 
t: UseQueriesProcedureRecord<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}, DecorateCreateRouterOptions<{
    post: BuiltRouter<{
        ctx: object;
        meta: object;
        errorShape: DefaultErrorShape;
        transformer: false;
    }, DecorateCreateRouterOptions<{
        byId: QueryProcedure<{
            input: {
                id: string;
            };
            output: {
                id: string;
                title: string;
            };
            meta: object;
            errorShape: DefaultErrorShape;
        }>;
    }>>;
    greeting: QueryProcedure<{
        input: {
            text: string;
        };
        output: {
            message: string;
        };
        meta: object;
        errorShape: DefaultErrorShape;
    }>;
}>>
t.
greeting: <{
    message: string;
}>(input: {
    text: string;
}, opts?: Omit<UseTRPCQueryOptions<{
    message: string;
}, {
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    message: string;
}>, "queryKey"> | undefined) => Omit<UseTRPCQueryOptions<{
    message: string;
}, {
    message: string;
}, TRPCClientError<{
    ctx: object;
    meta: object;
    errorShape: DefaultErrorShape;
    transformer: false;
}>, {
    message: string;
}>, "queryKey">
greeting({ text: stringtext: 'world' })],
  const myCustomContext: anymyCustomContext,
);