Nuxt/docs/content/3.docs/1.usage/1.data-fetching.md

# Data Fetching

Nuxt provides `useFetch`, `useLazyFetch`, `useAsyncData` and `useLazyAsyncData` to handle data fetching within your application.

::alert{icon=👉}
**`useFetch`, `useLazyFetch`, `useAsyncData` and `useLazyAsyncData` only work during `setup` or `Lifecycle Hooks`**
::

## `useAsyncData`

Within your pages, components and plugins you can use `useAsyncData` to get access to data that resolves asynchronously.

### Usage

```ts
const {
  data: Ref<DataT>,
  pending: Ref<boolean>,
  refresh: () => Promise<void>,
  error?: any
} = useAsyncData(
  key: string,
  handler: (ctx?: NuxtApp) => Promise<Object>,
  options?: {
    lazy: boolean,
    server: boolean,
    watch: WatchSource[]
  }
)
```

### Params

* **key**: a unique key to ensure that data fetching can be properly de-duplicated across requests
* **handler**: an asynchronous function that returns a value
* **options**:
  * _lazy_: whether to resolve the async function after loading the route, instead of blocking navigation (defaults to `false`)
  * _default_: a factory function to set the default value of the data, before the async function resolves - particularly useful with the `lazy: true` option
  * _server_: whether to fetch the data on server-side (defaults to `true`)
  * _transform_: a function that can be used to alter `handler` function result after resolving
  * _pick_: only pick specified keys in this array from `handler` function result
  * _watch_: watch reactive sources to auto refresh
  * _initialCache_: When set to `false`, will skip payload cache for initial fetch. (defaults to `true`)

Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the route before the data has been fetched. Consider using `lazy: true` and implementing a loading state instead for a snappier user experience.

### Return values

* **data**: the result of the asynchronous function that is passed in
* **pending**: a boolean indicating whether the data is still being fetched
* **refresh**: a function that can be used to refresh the data returned by the `handler` function
* **error**: an error object if the data fetching failed

By default, Nuxt waits until a `refresh` is finished before it can be executed again. Passing `true` as parameter skips that wait.

### Example

```ts [server/api/count.ts]
let counter = 0
export default () => {
  counter++
  return JSON.stringify(counter)
}
```

```vue [app.vue]
<script setup>
const { data } = await useAsyncData('count', () => $fetch('/api/count'))
</script>

<template>
  Page visits: {{ data }}
</template>
```

## `useLazyAsyncData`

This composable behaves identically to `useAsyncData` with the `lazy: true` option set. In other words, the async function does not block navigation. That means you will need to handle the situation where the data is `null` (or whatever value you have provided in a custom `default` factory function).

### Example

```vue
<template>
  <div>
    {{ pending ? 'Loading' : count }}
  </div>
</template>

<script setup>
const { pending, data: count } = useLazyAsyncData('count', () => $fetch('/api/count'))
watch(count, (newCount) => {
  // Because count starts out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>
```

## `useFetch`

Within your pages, components and plugins you can use `useFetch` to universally fetch from any URL.

This composable provides a convenient wrapper around `useAsyncData` and `$fetch`. It automatically generates a key based on URL and fetch options, as well as infers API response type.

### Usage

```ts
const {
  data: Ref<DataT>,
  pending: Ref<boolean>,
  refresh: (force?: boolean) => Promise<void>,
  error?: any
} = useFetch(url: string, options?)
```

Available options:

* `key`: Provide a custom key
* Options from [ohmyfetch](https://github.com/unjs/ohmyfetch)
  * `method`: Request method
  * `params`: Query params
  * `headers`: Request headers
  * `baseURL`: Base URL for the request
* Options from `useAsyncData`
  * `lazy`
  * `server`
  * `default`
  * `pick`
  * `transform`

The object returned by `useFetch` has the same properties as that returned by `useAsyncData` ([see above](#useasyncdata)).

### Example

```vue [app.vue]
<script setup>
const { data } = await useFetch('/api/count')
</script>

<template>
  Page visits: {{ data.count }}
</template>
```

## `useLazyFetch`

This composable behaves identically to `useFetch` with the `lazy: true` option set. In other words, the async function does not block navigation. That means you will need to handle the situation where the data is `null` (or whatever value you have provided in a custom `default` factory function).

### Example

```vue
<template>
  <!-- you'll need to handle a loading state -->
  <div v-if="pending">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>

<script setup>
const { pending, data: posts } = useLazyFetch('/api/posts')
watch(posts, (newPosts) => {
  // Because posts starts out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>
```

## Refreshing Data

Sometimes throughout the course of your user's page visit, you may need to refresh the data loaded from the API. This can happen if the user chooses to paginate, filter results, search, etc.

You can make use of the `refresh()` method returned from the `useAsyncData()` composable to refresh the data with different query parameters:

```vue
<script setup>
const page = ref(1);

const { data:users, loading, refresh, error } = await useFetch(() => `users?page=${page.value}&take=6`, { baseURL: config.API_BASE_URL }
);

function previous(){
  page.value--;
  refresh();
}

function next() {
  page.value++;
  refresh();
}
</script>
```

The key to making this work is to call the `refresh()` method returned from the `useFetch()` composable when a query parameter has changed.

### `refreshNuxtData`

Invalidate the cache of `useAsyncData`, `useLazyAsyncData`, `useFetch` and `useLazyFetch` and trigger the refetch.

This method is useful if you want to refresh all the data fetching for a current page.

### Usage

```ts
refreshNuxtData(keys?: string | string[])
```

Available options:

* `keys`: Provides an array of keys that used in `useAsyncData` to refetch. When it's not specified, all `useAsyncData` and `useFetch` will be refetched.

### Example

```vue
<template>
  <div>
    {{ pending ? 'Loading' : count }}
  </div>
  <button @click="refresh">Refresh</button>
</template>

<script setup>
const { pending, data: count } = useLazyAsyncData('count', () => $fetch('/api/count'))

const refresh = () => refreshNuxtData('count')
</script>
```

## Isomorphic fetch

When we call `fetch` in the browser, user headers like `cookie` will be directly sent to the API. But during server-side-rendering, since the `fetch` request takes place 'internally' within the server, it doesn't include the user's browser cookies, nor does it pass on cookies from the fetch response.

### Example: Bypass API headers to client

We can use [`useRequestHeaders`](/docs/usage/ssr) to access and proxy cookies to the API from server-side.

The example below adds the request headers to an isomorphic `fetch` call to ensure that the API endpoint has access to the same `cookie` header originally sent by the user.

```vue
<script setup>
const { data } = useFetch('/api/me', {
  headers: useRequestHeaders(['cookie'])
})
</script>
```

::alert{type="warning"}
Be very careful before proxying headers to an external API and just include headers that you need.

Not all headers are safe to be bypassed and might introduce unwanted behavior.

Here is a list of common headers that are NOT to be proxied:

* `host`, `accept`
* `content-length`, `content-md5`, `content-type`
* `x-forwarded-host`, `x-forwarded-port`, `x-forwarded-proto`
* `cf-connecting-ip`, `cf-ray`
::

### Example: Pass on cookies from server-side API calls on SSR response

 If you want to pass on/proxy cookies in the other direction, from an internal request back to the client, you will need to handle this yourself.

```ts [composables/fetch.ts]
export const fetchWithCookie = async (url: string, cookieName: string) => {
  const response = await $fetch.raw(url)
  if (process.server) {
    const cookies = Object.fromEntries(
      response.headers.get('set-cookie')?.split(',').map((a) => a.split('='))
    )
    if (cookieName in cookies) {
      useCookie(cookieName).value = cookies[cookieName]
    }
  }
  return response._data
}
```

```vue
<script setup lang="ts">
// This composable will automatically pass on a cookie of our choice.
const result = await fetchWithCookie("/api/with-cookie", "test")
onMounted(() => console.log(document.cookie))
</script>
```

## Best practices

The data returned by these composables will be stored inside the page payload. This means that every key returned that is not used in your component will be added to the payload.

::alert{icon=👉}
**We strongly recommend you only select the keys that you will use in your component.**
::

Imagine that `/api/mountains/everest` returns the following object:

```json
{
  "title": "Mount Everest",
  "description": "Mount Everest is Earth's highest mountain above sea level, located in the Mahalangur Himal sub-range of the Himalayas. The China–Nepal border runs across its summit point",
  "height": "8,848 m",
  "countries": [
    "China",
    "Nepal"
  ],
  "continent": "Asia",
  "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f6/Everest_kalapatthar.jpg/600px-Everest_kalapatthar.jpg"
}
```

If you plan to only use `title` and `description` in your component, you can select the keys by chaining the result of `$fetch` or `pick` option:

```vue
<script setup>
const { data: mountain } = await useFetch('/api/mountains/everest', { pick: ['title', 'description'] })
</script>

<template>
  <h1>{{ mountain.title }}</h1>
  <p>{{ mountain.description }}</p>
</template>
```

## Using async setup

If you are using `async setup()`, the current component instance will be lost after the first `await`. (This is a Vue 3 limitation.) If you want to use multiple async operations, such as multiple calls to `useFetch`, you will need to use `<script setup>` or await them together at the end of setup.

::alert{icon=👉}
Using `<script setup>` is recommended, as it removes the limitation of using top-level await. [Read more](https://vuejs.org/api/sfc-script-setup.html#top-level-await)
::

```vue
<script>
export default defineComponent({
  async setup() {
    const [{ data: organization }, { data: repos }] = await Promise.all([
      useFetch(`https://api.github.com/orgs/nuxt`),
      useFetch(`https://api.github.com/orgs/nuxt/repos`)
    ])

    return {
      organization,
      repos
    }
  }
})
</script>

<template>
  <header>
    <h1>{{ organization.login }}</h1>
    <p>{{ organization.description }}</p>
  </header>
</template>
```

## Directly calling an API Endpoint

There are instances where you may need to directly call the API. Nuxt 3 provides a globally available `$fetch` method using [unjs/ohmyfetch](https://github.com/unjs/ohmyfetch) (in addition to `fetch`)
with the same API as the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).

Using `$fetch` has a number of benefits, including:

It will handle 'smartly' making direct API calls if it's running on the server, or making a client-side call to your API if it's running on the client. (It can also handle calling third-party APIs.)

Plus, it comes with convenience features including automatically parsing responses and stringifying data.