Skip to main content

​
Overview

The FetchOptions interface extends the standard RequestInit and provides additional configuration for ofetch requests including base URL, query parameters, hooks, retry logic, and response parsing.

​
Type Signature

export interface FetchOptions<R extends ResponseType = ResponseType, T = any>
  extends Omit<RequestInit, "body">,
    FetchHooks<T, R> {
  baseURL?: string;
  body?: RequestInit["body"] | Record<string, any>;
  ignoreResponseError?: boolean;
  params?: Record<string, any>; // @deprecated use query instead
  query?: Record<string, any>;
  parseResponse?: (responseText: string) => any;
  responseType?: R;
  duplex?: "half" | undefined;
  dispatcher?: InstanceType<typeof import("undici").Dispatcher>;
  agent?: unknown;
  timeout?: number;
  retry?: number | false;
  retryDelay?: number | ((context: FetchContext<T, R>) => number);
  retryStatusCodes?: number[];
}

​
Options

​
baseURL

​
baseURL
string
Base URL to prepend to all requests. The request URL will be resolved against this base.
await ofetch('/users', {
  baseURL: 'https://api.example.com'
})
// Fetches: https://api.example.com/users

​
body

​
body
RequestInit['body'] | Record<string, any>
Request body. Accepts standard fetch body types or plain objects. Objects are automatically serialized to JSON and appropriate headers are set.
await ofetch('/users', {
  method: 'POST',
  body: { name: 'John', email: '[email protected]' }
})

​
ignoreResponseError

​
ignoreResponseError
boolean
default:"false"
When true, prevents ofetch from throwing errors for 4xx and 5xx status codes. The response will be returned normally instead.
const response = await ofetch('/users/404', {
  ignoreResponseError: true
})

​
query

​
query
Record<string, any>
Query parameters to append to the URL. Values are automatically URL-encoded.
await ofetch('/users', {
  query: { page: 1, limit: 10 }
})
// Fetches: /users?page=1&limit=10

​
params

​
params
Record<string, any>
Deprecated: Use query instead. Query parameters to append to the URL.

​
parseResponse

​
parseResponse
(responseText: string) => any
Custom function to parse response text. Defaults to JSON.parse for JSON responses.
await ofetch('/data', {
  parseResponse: (text) => customParser(text)
})

​
responseType

​
responseType
ResponseType
Expected response type. One of: "json", "text", "blob", "arrayBuffer", or "stream". Defaults to "json". See ResponseType.
const blob = await ofetch('/image.png', {
  responseType: 'blob'
})

const text = await ofetch('/file.txt', {
  responseType: 'text'
})

​
duplex

​
duplex
'half' | undefined
Experimental: Set to "half" to enable duplex streaming. Automatically set when using a ReadableStream as body.
await ofetch('/upload', {
  method: 'POST',
  body: readableStream,
  duplex: 'half'
})

​
dispatcher

​
dispatcher
InstanceType<typeof import('undici').Dispatcher>
Only supported in Node.js >= 18 using undici. Custom dispatcher for advanced request handling.
See undici documentation for details.

​
agent

​
agent
unknown
Only supported in older Node.js versions using node-fetch-native polyfill. Custom agent for HTTP(S) requests.

​
timeout

​
timeout
number
Request timeout in milliseconds. The request will be aborted if it takes longer than this value.
await ofetch('/slow-endpoint', {
  timeout: 5000 // 5 seconds
})

​
retry

​
retry
number | false
Number of times to retry failed requests. Set to false to disable retries. Defaults to 1 for GET requests and 0 for other methods.
await ofetch('/api/data', {
  retry: 3
})

​
retryDelay

​
retryDelay
number | ((context: FetchContext<T, R>) => number)
Delay between retries in milliseconds. Can be a number or a function that returns the delay based on the FetchContext.
// Fixed delay
await ofetch('/api/data', {
  retry: 3,
  retryDelay: 1000
})

// Dynamic delay (exponential backoff)
await ofetch('/api/data', {
  retry: 3,
  retryDelay: (context) => Math.pow(2, context.options.retry || 0) * 1000
})

​
retryStatusCodes

​
retryStatusCodes
number[]
HTTP status codes that should trigger a retry. Defaults to [408, 409, 425, 429, 500, 502, 503, 504].
await ofetch('/api/data', {
  retry: 3,
  retryStatusCodes: [429, 500, 502, 503]
})

​
Hooks

FetchOptions extends FetchHooks, providing lifecycle hooks:
​
onRequest
FetchHook | FetchHook[]
Called before the request is sent. See onRequest.
​
onRequestError
FetchHook | FetchHook[]
Called when the request fails. See onRequestError.
​
onResponse
FetchHook | FetchHook[]
Called after a successful response. See onResponse.
​
onResponseError
FetchHook | FetchHook[]
Called when the response has an error status (4xx, 5xx). See onResponseError.

​
Standard RequestInit Options

FetchOptions also includes all standard RequestInit options except body (which is redefined):
  • method - HTTP method (GET, POST, PUT, DELETE, etc.)
  • headers - Request headers
  • signal - AbortSignal for request cancellation
  • credentials - Credentials mode (omit, same-origin, include)
  • mode - Request mode (cors, no-cors, same-origin)
  • redirect - Redirect mode (follow, error, manual)
  • referrer - Referrer URL
  • referrerPolicy - Referrer policy
  • integrity - Subresource integrity value
  • keepalive - Keep connection alive
  • cache - Cache mode
See MDN RequestInit documentation for details.

​
Type Parameters

​
R
ResponseType
default:"ResponseType"
The expected response type. See ResponseType.
​
T
any
default:"any"
The expected type of the response data

Build docs developers (and LLMs) love

Get started for freeTalk to us