ofetch provides a query option to easily add search parameters to your requests.
Basic Usage
import { ofetch } from 'ofetch'
await ofetch('/api/users', {
query: { page: 1, limit: 10 }
})
// Request: /api/users?page=1&limit=10
Value Types
Query parameters support multiple value types:
await ofetch('/api/search', {
query: {
q: 'laptop', // string
minPrice: 100, // number → "100"
inStock: true, // boolean → "true"
category: null, // null → "" (empty string)
tags: ['tech', 'sale'] // array → multiple params
}
})
// Request: /api/search?q=laptop&minPrice=100&inStock=true&category=&tags=tech&tags=sale
Array Parameters
Arrays are automatically expanded into multiple parameters with the same key:
await ofetch('/api/products', {
query: {
id: [1, 2, 3]
}
})
// Request: /api/products?id=1&id=2&id=3
Object Parameters
Objects are automatically JSON-stringified:
await ofetch('/api/filter', {
query: {
filter: { price: { min: 10, max: 100 } }
}
})
// Request: /api/filter?filter=%7B%22price%22%3A%7B%22min%22%3A10%2C%22max%22%3A100%7D%7D
Undefined Values
Undefined values are automatically omitted:
await ofetch('/api/search', {
query: {
q: 'laptop',
category: undefined // This won't be included
}
})
// Request: /api/search?q=laptop
Merging with Existing Params
If your URL already has query parameters, the query option will merge with them:
await ofetch('/api/users?sort=name', {
query: { page: 1 }
})
// Request: /api/users?sort=name&page=1
Using with baseURL
Query parameters work seamlessly with baseURL:
const api = ofetch.create({
baseURL: 'https://api.example.com',
query: { apiKey: 'abc123' } // Added to all requests
})
await api('/users', {
query: { page: 1 } // Merged with baseURL query
})
// Request: https://api.example.com/users?apiKey=abc123&page=1
Deprecated: params Alias
The params option is deprecated. Use query instead.
// ❌ Deprecated
await ofetch('/api/users', {
params: { page: 1 }
})
// ✅ Use this instead
await ofetch('/api/users', {
query: { page: 1 }
})
Type Definition
From src/types.ts:34-36:
/**
* @deprecated use query instead.
*/
params?: Record<string, any>
query?: Record<string, any>
Implementation Details
ofetch uses URLSearchParams internally for robust query parameter handling. The logic is implemented in src/utils.url.ts:64-103.