use-fetch

Fetch typed data with a custom parse decoder.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useFetch } from "@vizejs/composable/use-fetch";

Try it

Check for updates on request

Fetch JSON on demand with explicit loading, success and error states.

Open the interactive example

What to observe: Check for updates shows Checking… and then Latest version: 0.449.0.

immediate: false waits for execute(). Replace the data URL with your endpoint; timeoutMs, retry and abort() are available.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useFetch } from "@vizejs/composable/use-fetch";

// Replace the data URL with your API endpoint.
const endpoint = `data:application/json,${encodeURIComponent('{"latest":"0.449.0"}')}`;
const { data, status, execute } = useFetch<{ latest: string }>(endpoint, { immediate: false });
</script>

<template>
  <div class="composable-example">
    <p>Fetch JSON when the reader asks, and show loading, result and error states.</p>
    <button type="button" :disabled="status === 'pending'" @click="() => execute()">
      Check for updates
    </button>
    <output aria-live="polite">{{
      status === "success"
        ? `Latest version: ${data?.latest}`
        : status === "error"
          ? "Could not check for updates."
          : status === "pending"
            ? "Checking…"
            : "Not checked yet."
    }}</output>
  </div>
</template>

Runtime contract

API

useFetch

Fetch typed data with a custom parse decoder.

function useFetch<Data>( url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseFetchOptions<Data> & { readonly parse: (response: Response) => Promise<Data> }, ): FetchControls<Data>

useFetch

Fetch a non-JSON body whose type follows responseType.

function useFetch<const Kind extends Exclude<FetchResponseType, "json">>( url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseFetchOptions<FetchResponseTypeMap[Kind]> & { readonly responseType: Kind }, ): FetchControls<FetchResponseTypeMap[Kind]>

useFetch

Fetch JSON. Supply validate to narrow unknown to a checked type.

function useFetch<Data = unknown>( url: MaybeRefOrGetter<string | URL | null | undefined>, options?: UseFetchOptions<Data> & { readonly responseType?: "json" }, ): FetchControls<Data>

useFetch

Reactive, abortable, retrying fetch with typed decoding and interceptors. Latest wins: starting an execution aborts the pending one, which then settles as "superseded" without touching state. The pending request is aborted when the owning reactive scope stops; outside a scope the caller owns abort(). Automatic execution (initial and on reactive URL/init changes) only happens in a browser or with an explicit fetch, so server rendering performs no I/O unless you await execute() in onServerPrefetch; state then holds initialData and status "idle".

function useFetch<Data>( url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseFetchOptions<Data> = {}, ): FetchControls<Data>

const id = ref(1);
const { data, error } = useFetch(() => `/api/users/${id.value}`, {
  validate: isUser,
  retry: 2,
  timeoutMs: 5_000,
});

Types

FetchResponseTypeMap

Data type produced by each built-in FetchResponseType.

FetchRequest

Request description passed through the beforeRequest interceptor.

FetchBeforeRequestContext

Context supplied to the beforeRequest interceptor.

FetchAfterResponseContext

Context supplied to the afterResponse interceptor.

UseFetchOptions

Options for useFetch.

FetchControls

Reactive state and controls returned by useFetch.