---
title: "Usage"
description: "Learn how to use strapi module in your Nuxt application."
canonical_url: "https://strapi.nuxtjs.org/usage"
---
# Usage

> Learn how to use strapi module in your Nuxt application.

> This module exposes composables that are [auto-imported](https://nuxt.com/docs/guide/directory-structure/composables) by Nuxt.

## `useStrapi`

Depending on which version you have in your [options](https://strapi.nuxtjs.org/setup#options), you will be using either the v5 (default), v4 or v3 client.

<tip>

All examples below are demonstrated with the default v5 `useStrapi()`. <br />



<br />

Note that v3/v4 expose similar methods with different options. Check out specific types for [v5](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts), [v4](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v4.ts) or [v3](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v3.ts).

</tip>

> Learn how to handle Strapi errors globally by using [nuxt hooks](https://strapi.nuxtjs.org/advanced#errors-handling).

<warning>

All examples below are demonstrated with http calls in script setup. However, to handle SSR properly you may want to use [useAsyncData](https://strapi.nuxtjs.org/advanced#async-data).

</warning>

When using the composable, you can pass in a default data model for all methods.

```ts
const { findOne } = useStrapi<Course>()

// typed to Course
findOne('courses', '123')
```

If you prefer not to use a default data type and want to override the default, you can pass the data model on individual methods as well.

```ts
const { findOne } = useStrapi<Course>()

// typed to SpecialCourse
findOne<SpecialCourse>('courses', '123')
```

### `find`

Get a list of documents. Returns entries matching the query filters (see [parameters](https://docs.strapi.io/cms/api/rest/parameters) documentation).

- **Arguments:**
  - contentType: `string`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts)
  - fetchOptions?: [`FetchOptions`](https://github.com/unjs/ofetch/blob/main/src/types.ts#L34)
- **Returns:** `Promise<Strapi5ResponseMany<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const { find } = useStrapi()

const response = await find<Restaurant>('restaurants')
</script>
```

> Check out the Strapi [Get documents](https://docs.strapi.io/cms/api/rest#get-documents) REST API endpoint.

### `findOne`

Returns a document by `documentId`.

- **Arguments:**
  - contentType: `string`
  - documentId: `string`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts) (without `filters`)
  - fetchOptions?: [`FetchOptions`](https://github.com/unjs/ofetch/blob/main/src/types.ts#L34)
- **Returns:** `Promise<Strapi5ResponseSingle<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const route = useRoute()
const { findOne } = useStrapi()

const response = await findOne<Restaurant>('restaurants', route.params.id)
</script>
```

> Check out the Strapi [Get a document](https://docs.strapi.io/cms/api/rest#get-a-document) REST API endpoint.

### `create`

Creates a document and returns its value.

- **Arguments:**
  - contentType: `string`
  - data: `Partial<T>`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts) (without `filters`)
- **Returns:** `Promise<Strapi5ResponseSingle<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const { create } = useStrapi()

const onSubmit = async () => {
  await create<Restaurant>('restaurants', { name: 'My restaurant' })
}
</script>
```

> Check out the Strapi [Create a document](https://docs.strapi.io/cms/api/rest#create-a-document) REST API endpoint.

### `update`

Partially updates a document by `documentId` and returns its value. Fields that aren't sent in the query are not changed in the database. Send a `null` value if you want to clear them.

- **Arguments:**
  - contentType: `string`
  - documentId: `string`
  - data?: `Partial<T>`
  - params?: [`Strapi5RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v5.ts) (without `filters`)
- **Returns:** `Promise<Strapi5ResponseSingle<T>>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const route = useRoute()
const { update } = useStrapi()

const onSubmit = async () => {
  await update<Restaurant>('restaurants', route.params.id, { name: 'My updated restaurant' })
}
</script>
```

> Check out the Strapi [Update a document](https://docs.strapi.io/cms/api/rest#update-a-document) REST API endpoint.

### `delete`

Deletes a document by `documentId`. Returns no content (204).

- **Arguments:**
  - contentType: `string`
  - documentId?: `string`
  - params?: `{ locale?: StrapiLocale }`
- **Returns:** `Promise<void>`

```vue
<script setup lang="ts">
const route = useRoute()
const { delete: _delete } = useStrapi()

const onSubmit = async () => {
  await _delete('restaurants', route.params.id)
}
</script>
```

<tip>

Pass `locale` to delete a specific locale version: `_delete('restaurants', id, { locale: 'fr' })`

</tip>

> Check out the Strapi [Delete a document](https://docs.strapi.io/cms/api/rest#delete-a-document) REST API endpoint.

### `count`

Returns the count of entries matching the query filters. You can read more about parameters [here](https://docs-v3.strapi.io/developer-docs/latest/developer-resources/content-api/content-api.html#api-parameters).

<warning>

Available only for `v3` as Strapi v4 can do the same thing with the [Pagination queries](https://docs.strapi.io/developer-docs/latest/developer-resources/database-apis-reference/rest-api.html#pagination) of the `find` method.

</warning>

- **Arguments:**
  - contentType: `string`
  - params?: [`Strapi3RequestParams`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/v3.ts#L9)
- **Returns:** `Promise<number>`

```vue
<script setup lang="ts">
const { count } = useStrapi()

const total = await count('restaurants')
</script>
```

> Check out the Strapi v3 [Count entries](https://docs-v3.strapi.io/developer-docs/latest/developer-resources/content-api/content-api.html#count-entries) REST API endpoint.

## `useStrapiGraphQL`

This composable is an alias of `useStrapiClient` that sets the `url` to `/graphql` and `method` to `POST`. You can use this method to send an authenticated GraphQL query to your API. See [Use Imported GraphQL](https://strapi.nuxtjs.org/advanced#use-imported-graphql) to use Option 2 below.

- **Arguments:**
  - query: `string|DocumentNode`
  - variables (optional): [`StrapiGraphqlVariables`](https://github.com/nuxt-modules/strapi/blob/main/src/runtime/types/index.ts#L570)
- **Returns:** `Promise<T>`

```vue
<script setup lang="ts">
const route = useRoute()
const graphql = useStrapiGraphQL()

// Option 1: use inline query
const restaurant = await graphql(`
  query {
    restaurant(documentId: "${route.params.id}") {
      documentId
      name
    }
  }
`)

// Option 2: use imported query
const restaurant = await graphql(query, { id: route.params.id })
</script>
```

## `useStrapiClient`

This composable is a wrapper around [Nuxt `$fetch` helper](https://nuxt.com/docs/api/utils/dollarfetch) that uses [`ofetch`](https://github.com/unjs/ofetch) under the hood. You can use this method to reach custom strapi endpoints not available in the `useStrapi` composable.

- **Arguments:**
  - url: `string`
  - fetchOptions?: [`FetchOptions`](https://github.com/unjs/ofetch/blob/main/src/types.ts#L34)
- **Returns:** `Promise<T>`

```vue
<script setup lang="ts">
import type { Restaurant } from '~/types'

const client = useStrapiClient()

const restaurant = await client<Restaurant>('/restaurants', { method: 'POST', body: { name: 'My restaurant' } })
</script>
```

## `useStrapiUrl`

This composable is an helper to get the strapi url endpoint. It is used internally to reach the api in the `useStrapiClient` composable.

```vue
<script setup>
const url = useStrapiUrl()
</script>
```

## `useStrapiVersion`

This composable is an helper to get version defined in options. It is used internally to compute the `useStrapiUrl` composable.

```vue
<script setup>
const version = useStrapiVersion()
</script>
```

## `useStrapiMedia`

This composable is a helper to get the full URL for media. Strapi endpoints return media URLs as relative paths (e.g. `/uploads/image.png`) on self-hosted instances, or absolute URLs on Strapi Cloud. This composable handles both cases automatically.

```vue
<script setup>
const imageUrl = useStrapiMedia('/uploads/image.png')
</script>
```


## Sitemap

See the full [sitemap](https://strapi.nuxtjs.org/sitemap.md) for all pages.