A Vue composable for simplified GET requests with @tanstack/vue-query
npm install vue-query-request-utils@tanstack/vue-query
useGetQuery) and mutations (useSend)
bash
npm install vue-query-request-utils
or
yarn add vue-query-request-utils
or
pnpm add vue-query-request-utils
`
Peer Dependencies
This package requires the following peer dependencies:
@tanstack/vue-query (required): Provides the core query and mutation functionality. Install the latest version (e.g., ^5.92.0 as of January 2026) for optimal compatibility.
vue (required): The Vue.js framework (version ^3.0.0 or higher).
axios (optional): Required only if using Axios as your HTTP client (version ^1.13.2 or higher as of January 2026). If you prefer native Fetch, you can use the built-in createFetchClient utility insteadβno Axios needed.
`bash
npm install @tanstack/vue-query vue
`
If using Axios:
`bash
npm install axios
`
π Usage
Setting Up the HTTP Client
You can use either Axios or a Fetch-based client. Provide the client globally (e.g., via provideApi in your app setup or Nuxt plugin) or override per-composable via the API prop.
#### Using Axios
`ts
// api.ts
import axios from 'axios';
export const API = axios.create({
baseURL: 'https://api.example.com',
});
`
#### Using Fetch (No Axios Required)
`ts
// api.ts
import { createFetchClient } from 'vue-query-request-utils';
export const API = createFetchClient('https://api.example.com');
`
useGet (GET Requests)
Fetch data with caching and loading states:
`vue
Loading...
{{ error.message }}
- {{ user.name }}
`
Parameter Examples
Plain Query Params:
`ts
paramRef: { page: 1, active: true }
// β /users?page=1&active=true
`
Dynamic Route Segments:
`ts
paramRef: [123]
// β /users/123
`
Full Path and Query:
`ts
paramRef: {
path: [123],
query: { active: true, page: 1 }
}
// β /users/123?active=true&page=1
`
paramRef supports plain values, refs, or computed refs for reactivity.
All of the above support ref or computed values.
useSend (POST, PUT, PATCH, DELETE Requests)
Perform mutations to create, update, or delete data:
`vue
User created successfully!
{{ error.message }}
`
With URL Parameters
Similar to useGet, use paramRef for dynamic URLs:
`ts
useSend({
method: 'patch',
url: '/users',
paramRef: { path: [123], query: { version: 2 } }, // Builds: /users/123?version=2
bodyRef: { name: 'Updated Name' }, // Fallback body if mutate() has no variables
// ...
});
`
#### With Fallback Body
If mutate() is called without variables, bodyRef is used (supports reactivity).
Using with Nuxt 3
The composables work seamlessly with Nuxt 3 and 4. Use them in your setup scripts or provide the Axios instance via a Nuxt plugin:
$3
`ts
// plugins/api.ts
import { defineNuxtPlugin } from '#app';
import axios from 'axios';
import { provideApi } from 'vue-query-request-utils'
export default defineNuxtPlugin(() => {
const API = axios.create({ baseURL: 'https://api.example.com' });
nuxtApp.vueApp.use(provideApi(API));
});
`
π§ͺ Advanced Usage
Custom Axios
`ts
useGet({
API: customAxios,
url: "/example",
...
})
`
$3
`ts
// plugins/api.ts
import { defineNuxtPlugin } from '#app';
import { provideApi, createFetchClient } from 'vue-query-request-utils';
export default defineNuxtPlugin(() => {
const API = createFetchClient('https://api.example.com');
nuxtApp.vueApp.use(provideApi(API));
});
`
In components (no API prop needed if provided globally):
`vue
`
π API Reference
useGet
A composable for GET requests with @tanstack/vue-query.
Parameters:
- url: API endpoint (e.g., /users).
- queryKey: Unique key for caching (e.g., ['users'] or a Vue Ref).
- API?: Override HTTP client (AxiosInstance, HttpClient, or base URL string).
- paramRef?: Optional query parameters (e.g., { page: 1 }).
- options?: Additional useQuery options (e.g., { enabled: false }).
Returns:
UseQueryResult with:
- data: Fetched data.
- isLoading: Loading state.
- error: Error details, if any.
- refetch: Function to refetch data.
useSend
A composable for POST, PUT, PATCH, or DELETE requests.
Parameters:
- method: HTTP method (post, put, patch, delete).
- url: API endpoint (e.g., /users).
- API?: Override HTTP client (AxiosInstance, HttpClient, or base URL string).
- paramRef?: Optional URL parameters (supports path/query; reactive).
- bodyRef?: Fallback request body (reactive; used if mutate() has no variables).
- config?: Extra request config (AxiosRequestConfig or RequestInit).
- mutationKey?: Unique key for the mutation (e.g., ['createUser']).
- options?: Additional useMutation options (e.g., { onSuccess }).
Returns:
UseMutationResult` with properties like: