Query Parameters

Add URL search parameters using the query option

ofetch provides a query option to easily add search parameters to your requests.

Basic Usage

Query option

import { ofetch } from 'ofetch'

await ofetch('/api/users', {
  query: { page: 1, limit: 10 }
})
// Request: /api/users?page=1&limit=10

// Without ofetch
const params = new URLSearchParams({ page: '1', limit: '10' })
await fetch(`/api/users?${params}`)

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.