Using useFetch in the Vue 3 Composition API

In the Vue 3 ecosystem, data fetching has long been a core pain point for frontend development. With the introduction of the Composition API, utility functions like createFetch and useFetch have emerged to address code redundancy and complexity in state management caused by traditional asynchronous operations (such as Promises or async/await). This article delves into how useFetch works, its configuration options, and best practices for real-world projects.
In the Vue 2 era, we typically relied on Vuex or Pinia to manage global state, while data fetching was often implemented through manually written Promise chains or async/await blocks. This approach not only resulted in poor code readability but also failed to leverage the powerful reactivity system features of Vue 3.

The Vue 3 Composition API allows us to group related logic together, enabling data fetching, loading states, and error handling to integrate more naturally into a component's lifecycle. useFetch is a concrete manifestation of this philosophy; by returning an object containing data, loading, and error, it allows developers to manage asynchronous data streams in a declarative manner.

Basic Usage and Return Structure

The core advantage of the useFetch function lies in its concise API design. Simply passing the request URL or a Fetch instance to this function automatically handles network requests, response parsing, and error catching.

import { useFetch } from 'vue-demi' // Assuming usage of vue-demi or similar library

const { data, loading, error } = useFetch('/api/users')

Upon execution of the above code, the component receives three key states:

  • data: The data object returned upon successful request, initially set to null.
  • loading: A boolean value that is true while the request is in progress and false once completed.
  • error: Error information returned when the request fails, initially set to undefined.

This structure allows developers to access the latest state directly without manually defining intermediate variables, significantly simplifying logic within templates.

Configuration Options and Advanced Features

While the basic usage is already quite powerful, useFetch typically supports a rich set of configuration options to meet the needs of complex scenarios. Common configuration items include:

  • query: Allows dynamically adding query parameters to the URL.
  • options: Customizes extra headers or timeout settings for Fetch requests.
  • transform: Enables custom processing of response data (e.g., formatting dates, converting formats).
  • refetch: Controls whether failed requests are automatically retried or manually refreshed.
const { data, loading } = useFetch(
  'https://api.example.com/data',
  {
    query: { id: 123 },
    options: { headers: { 'Authorization': 'Bearer token' } },
    transform: (res) => res.json() // Automatically parse JSON
  }
)

Through the transform option, developers can avoid duplicating parsing logic within the component, keeping the code clean and maintainable.

Reactive Updates and Side Effect Management

A significant feature of useFetch is its ability to automatically respond to URL changes. When a parent component modifies the passed query parameters or base URL, the useFetch within child components will automatically initiate new requests and update the state. This mechanism eliminates the necessity for manually calling fetch, making data flows more fluid.

Furthermore, for scenarios requiring side effects (such as sending POST requests), useFetch is typically used in conjunction with other Composition API functions like onMounted or a custom useMutation. This combination pattern retains the declarative advantages of Fetch while meeting complex business logic requirements.

Practical Example: User List Display

Below is a complete example demonstrating how to use useFetch within a Vue 3 component to load and render a user list:

<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">{{ error.message }}</div>
  <ul v-else>
    <li v-for="user in data" :key="user.id">
      {{ user.name }} - {{ user.email }}
    </li>
  </ul>
</template>

<script setup>
import { useFetch } from 'vue-demi'

const { data, loading, error } = useFetch('/api/users')

// Automatically refresh data when URL changes
watch(() => location.search, () => {
  // Optional: Add additional logic here, such as adjusting request headers based on parameters
})
</script>

In this example, the template section is entirely built upon reactive states, eliminating the need for manual asynchronous flow handling. Once the API returns data, the list renders automatically; if an error occurs, a friendly message is displayed; and during loading, a placeholder is shown.

Summary and Outlook

useFetch is an indispensable part of the Vue 3 Composition API ecosystem. By abstracting the underlying details of network requests, it allows developers to focus on the business logic itself. Compared to the traditional async/await pattern, not only is the code more concise, but it also better utilizes Vue's reactivity system. As the Vue ecosystem continues to evolve, such utility functions will continue to optimize, providing stronger support for building high-performance, easy-to-maintain single-page applications.