# Installation

## Setup

1. **Install Sanity integration**
   ```bash
   npx nuxi@latest module add sanity
   ```
2. **Enable the module in your Nuxt configuration**
   ```ts \[nuxt.config.ts]
   export default defineNuxtConfig({
     modules: ['@nuxtjs/sanity']
   })
   ```
3. **Add Sanity configuration**:br This module will look for a `~~/cms/sanity.config.ts` file relative to your project's root directory. Alternatively, you can pass in an object in your Nuxt config with key details.
   ```ts \[nuxt.config.ts]
   export default defineNuxtConfig({
     modules: ['@nuxtjs/sanity'],
     sanity: {
       projectId: 'myProject'
     }
   })
   ```
   :tip[You can find more about configuring `@nuxtjs/sanity` [here](sanity.nuxtjs.org/getting-started/configuration).]
4. **You're good to go!**:br Check out [how to use Sanity](sanity.nuxtjs.org/getting-started/usage){.text-primary-500}.


# Configuration

By default, `@nuxtjs/sanity` will look for a `~~/cms/sanity.config.ts` file relative to your project's root directory, and it will read your `projectId` and `dataset` from there.

```ts [sanity.config.ts]
import { defineConfig } from 'sanity'

export default defineConfig({
  projectId: '<sample-project-id>',
  dataset: 'production',
  // rest of your configuration
})
```

If you need to provide additional configuration, you can pass in an object in your Nuxt config with key details:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    projectId: 'myProject',
    apiVersion: '2021-10-18'
  },
})
```

## Runtime configuration

It is also possible to pass options to this module through [runtime configuration](https://nuxtjs.org/guide/runtime-config/){rel="&#x22;nofollow&#x22;"}, via a `sanity` key. If you do so they will be merged with (and override) any other options passed in.

For example:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  runtimeConfig: {
    sanity: {
      token: process.env.NUXT_SANITY_TOKEN,
    },
  },
  sanity: {
    projectId: 'myProject',
  },
})
```

## Reference

### `globalHelper`

- Type: **boolean**
- Default: **false**

Whether to provide a global `$sanity` helper that you can use throughout your project. (It's recommended not to do this but to use the `useSanity` and `useSanityQuery` composables.)

### `projectId`

- **Required**
- Type: **string**

Your Sanity Project ID, which you can find in your Sanity dashboard.

![Sanity dashboard](sanity.nuxtjs.org/sanity-dashboard.png)

### `dataset`

- Type: **string**
- Default: &#x2A;*`'production'`**

### `apiVersion`

- Type: **string**
- Default: &#x2A;*`'1'`**

You can specify the Sanity API version to use. [More info here.](https://www.sanity.io/help/js-client-api-version){rel="&#x22;nofollow&#x22;"}

### `token`

- Type: **string**

You can provide a token or leave blank to be an anonymous user. (You can also set a token programmatically in a Nuxt plugin.)

### `withCredentials`

- Type: **boolean**
- Default: &#x2A;*`false`**

Include credentials in requests made to Sanity. Useful if you want to take advantage of an existing authorisation to the Sanity CMS.

### `useCdn`

- Type: **boolean**
- Default: &#x2A;*`true`**

### `minimal`

- Type: **boolean**
- Default: &#x2A;*`false`**

Use an ultra-minimal Sanity client for making requests (a fork of [picosanity](https://github.com/rexxars/picosanity){rel="&#x22;nofollow&#x22;"} with SSR-specific changes). It only supports `fetch` requests, but will significantly decrease your bundle size.

::tip
If you don't have 

`@sanity/client`

 installed, then 

`@nuxtjs/sanity`

 will use the minimal client by default.
::

### `disableSmartCdn`

- Type: **boolean**
- Default: &#x2A;*`false`**

By default, if [Preview Mode](https://nuxtjs.org/docs/2.x/features/live-preview){rel="&#x22;nofollow&#x22;"} has been switched on, `useCdn` will be disabled. If this behaviour isn't desirable, you can disable it by setting `{ disableSmartCdn: false }`.

### `additionalClients`

- Type: **Object**
- Default: &#x2A;*`{}`**

You can create additional clients. Each client's name will be the key of the object provided, and the options provided will be merged with the options of the default client.

The options that can be provided are:

- `projectId`
- `dataset`
- `token`
- `withCredentials`
- `useCdn`

So, for example:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    additionalClients: {
      another: {
        projectId: 'anotherproject',
      },
    },
  },
})
```

### `visualEditing`

- Type: **Object**
- Default: **undefined**

Used to enable and configure Visual Editing. See the [Visual Editing](sanity.nuxtjs.org/getting-started/visual-editing) section for more details.

### `typegen`

- Type: **Object**
- Default: **undefined**

Used to enable and configure automatic TypeScript type generation for GROQ queries. See the [Type Generation](sanity.nuxtjs.org/getting-started/typegen) section for more details.

Available options:

| Option                  | Type                | Default                                      | Description                                         |
| ----------------------- | ------------------- | -------------------------------------------- | --------------------------------------------------- |
| `enabled`               | `boolean`           | `false`                                      | Enable type generation                              |
| `schemaTypesPath`       | `string`            | -                                            | Path to schema types module (required when enabled) |
| `schemaTypesExport`     | `string`            | `'schemaTypes'`                              | Export name to read schema types from               |
| `queryPaths`            | `string | string[]` | `['**/*.{ts,tsx,js,jsx,mjs,cjs,vue,astro}']` | Glob patterns for files to scan                     |
| `overloadClientMethods` | `boolean`           | `true`                                       | Generate `@sanity/client` method overloads          |

### `queryEndpoint`

- Type: **String**
- Default: **undefined**

The endpoint that `useSanityQuery` requests are sent to. See the [Usage](sanity.nuxtjs.org/getting-started/usage) section for more details.


# Usage

`@nuxtjs/sanity` provides key composables to interact with data from your Sanity project.

1. `useSanityQuery` and `useLazySanityQuery`. These composables allow automatic fetching of Sanity queries.
2. `useSanity`. This is the most customisable way to access data from your Sanity project, and exposes a Sanity client you can use to perform fetches or more advanced patterns (like subscribing to updates).

## useSanityQuery

This is a data fetching composable that wraps `useAsyncData` from Nuxt (see [docs](https://nuxt.com/docs/getting-started/data-fetching#useasyncdata){rel="&#x22;nofollow&#x22;"}).

The only mandatory argument is the query for it to fetch. You can also pass params, and an options object. In addition to the options you can pass to `useAsyncData`, there is also a `client` option for specifying which configured Sanity client you would like to use.

If you pass any ref/computed parameters in `params`, `useSanityQuery` will automatically refetch the query when these parameters change.

### Example

```ts
const query = groq`*[_type == "post" && topic == $topic][0..10]`
const { data, refresh } = useSanityQuery(query, { topic: 'News' })
```

You can also type the result of your query by passing a generic to `useSanityQuery`:

```ts
// data will be typed as Ref<Post | null>
const query = groq`*[_type == "post" && topic == $topic][0..10]`
const { data, refresh } = useSanityQuery<Post>(query, { topic: 'News' })
```

### Query Options

You can pass a `queryOptions` object to customise the options sent to the underlying Sanity client fetch call. This allows you to override the automatically resolved options for specific queries.

```ts
const { data } = useSanityQuery(query, params, {
  queryOptions: {
    perspective: 'published',
    tag: 'my-custom-tag',
    useCdn: false,
  },
})
```

Any options passed via `queryOptions` will take priority over the module's automatically resolved values. See the [`@sanity/client` documentation](https://www.sanity.io/docs/js-client#fetch){rel="&#x22;nofollow&#x22;"} for the full list of available options.

### Automatic Type Generation

When [type generation](sanity.nuxtjs.org/getting-started/typegen) is enabled, you can use auto-generated types based on your query variable names:

```ts
// Query variable: postsQuery -> Generated type: PostsQueryResult
const postsQuery = groq`*[_type == "post" && topic == $topic][0..10]`
const { data, refresh } = useSanityQuery<PostsQueryResult>(postsQuery, { topic: 'News' })
```

See the [Type Generation](sanity.nuxtjs.org/getting-started/typegen) guide for setup instructions.

## useLazySanityQuery

This is an equivalent query that does not block client-side navigation and uses `useLazyAsyncData` under the hood. Other than that, the API is identical to `useSanityQuery` above.

## useSanity

You can access a Sanity helper/client throught your application with the globally available `useSanity()` composable.

Unlike `useSanityQuery` and `useLazySanityQuery`, `useSanity` is also available within your Nitro server routes in exactly the same way as within your Nuxt app.

::tip
If you want to access this helper globally through 

`$sanity`

 \- as in a prior version of this module - ensure you've set the 

`globalHelper`

 option to true.
::

### Reference

#### `fetch`

This enables you to perform a GROQ query against your Sanity dataset. By default it returns a `Promise<unknown>` although you can customise the type of the return.

##### Example with `asyncData`

:br

::code-group
```html [JavaScript]
<script setup>
const query = groq`{ "articles": *[_type == "article"] }`

const sanity = useSanity()

const { data } = await useAsyncData('articles', () => sanity.fetch(query))
</script>
```

```html [TypeScript]
<script setup lang="ts">
const query = groq`{ "articles": *[_type == "article"] }`

const sanity = useSanity()

// By default it returns a `Promise<unknown>`,
// but you can customise the type of the return.
const { data } = await useAsyncData('articles', () => sanity.fetch<{ articles: Article[] }>(query))
</script>
```
::

#### `client`

You can access the underlying client with this property. This is most useful if not using the minimal client.

```ts
const query = groq`*[_type == "article"][0].title`

export default defineComponent({
  setup() {
    const sanity = useSanity()
    onMounted(() => {
      const observable = sanity.client.listen(query)
      observable.subscribe(event => {
        // Do something
      })
    })
  },
})
```

#### `setToken`

You can securely set the token for your Sanity client in a Nuxt plugin.

```js [plugins/sanity.server.ts]
export default defineNuxtPlugin((nuxtApp) => {
  const sanity = useSanity()
  const token = getTokenFromReq(nuxtApp.ssrContext.req)
  sanity.setToken(token)
})
```

#### `config`

You can access the Sanity config you have passed into the module if you need to do so (for example, with `@sanity/image-url`):

```js [plugins/sanity.ts]
import imageUrlBuilder from '@sanity/image-url'
export default defineNuxtPlugin(() => {
  const sanity = useSanity()
  const builder = imageUrlBuilder(sanity.config)

  function urlFor(source) {
    return builder.image(source)
  }

  return {
    provide: { urlFor }
  }
})
```

#### Additional clients

If you have [configured additional clients](sanity.nuxtjs.org/getting-started/configuration#additionalclients) you can access them by passing in a client name to `useSanity`. It returns a sanity helper, with all the same properties and methods as specified above. So, for example:

```js [plugins/fetch.ts]
export default defineNuxtPlugin(() => {
  const otherSanityHelper = useSanity('other')
  otherSanityHelper.fetch('*[type == "article"][0]')
})
```

#### Private Datasets

You can use the `queryEndpoint` configuration option to set the endpoint for all requests made with `useSanityQuery`. This is especially useful when querying private datasets or making requests that require tokens that cannot be safely exposed on the client.

This module does not provide a built-in handler for proxying queries to private datasets. Instead, it includes a convenience function that makes it straightforward to implement a server-side handler for most use cases.

To control which queries can be made against a private dataset, you can use `validateSanityQuery`. At build time, the module scans your codebase, extracts all GROQ queries, and compiles them into a whitelist. At runtime, incoming queries are checked against this list, and by default an error is thrown if a query is not recognized. You can optionally limit extraction to specific files via the function’s second argument.

```ts [server/api/fetch.ts]
export default defineEventHandler(async (event) => {
  const { query, params = {}, options } = await readBody(event)

  await validateSanityQuery(query)

  const sanity = useSanity()
  const client = sanity.client.withConfig({ token: process.env.NUXT_SANITY_READ_TOKEN })

  return client.fetch(query, params, options)
})
```

::warning
`validateSanityQuery` only validates query strings, not parameters. If you define queries that use dynamic parameters, you must ensure those queries are safe to run with any parameter value.

```ts
// Validate parameter values before executing queries
const allowedCategories = ['tech', 'news', 'sports']
if (params.category && !allowedCategories.includes(params.category)) {
  throw createError({ statusCode: 400, message: 'Invalid category' })
}
```
::


# Visual Editing

## Overview

`@nuxtjs/sanity` provides a simple method of integrating [visual editing](https://www.sanity.io/docs/visual-editing){rel="&#x22;nofollow&#x22;"} in your Nuxt application. Before enabling this feature, make sure you have [Presentation](https://www.sanity.io/docs/presentation){rel="&#x22;nofollow&#x22;"} installed in your studio.

You will also need to install `@sanity/client`:

::code-group
```bash [pnpm]
pnpm install @sanity/client
```

```bash [NPM]
npm install @sanity/client --save
```
::

::warning
The 

`minimal`

 client must not be enabled.
::

## Configuration

You can configure visual editing via the `sanity.visualEditing` key in your Nuxt config. The following options are available:

#### `studioUrl`

- **Required**
- Type: **string**

The URL of the Sanity Studio with Presentation installed.

#### `token`

- **Required**
- Type: **string**

A Sanity read token used for server side queries. This is required in order to fetch draft content. This value will not be exposed to the client.

#### `mode`

- Type: **string**
- Default: &#x2A;*`'live-visual-editing'`**

Accepts one of the following options:

- **`'live-visual-editing'`** - Default behaviour. Lets the module handle setup to provide fully featured visual editing with live updates. Queries should be executed using `useSanityQuery`.
- **`'visual-editing'`** - Used to enable visual editing without live updates, for example if fetching data using the Sanity client directly. Passing a custom `refresh` handler is recommended, as by default the entire app will refresh to display updates.
- **`'custom'`** - The module will not handle any setup, instead the `useSanityVisualEditing` and/or `useSanityLiveMode` composables will need to be called manually.

#### `previewMode`

- Type: **boolean**, **object**
- Default: **true**

To enable preview mode with defaults, or optionally configure the endpoints used to enable and disable preview mode. If passing an object, the options that can be provided are:

- `enable` - the path of the enable endpoint, defaults to `/preview/enable`
- `disable` - the path of the disable endpoint, defaults to `/preview/disable`

#### `stega`

- Type: **boolean**
- Default: **true**

Used to enable or disable [stega](https://www.sanity.io/docs/loaders-and-overlays#1dbcc04a7093){rel="&#x22;nofollow&#x22;"}.

#### `keepStegaOnCopy`

- Type: **boolean**
- Default: **false**

While visual editing is enabled, stega-encoded metadata (invisible characters) is automatically stripped from clipboard data when content is copied from the page, so copied text can be pasted into other tools without the hidden characters tagging along. Set this option to `true` to opt out and keep stega in copied content.

#### `onSuspiciousStega`

- Type: **function**

An optional callback that reports stega payloads found in places where they always cause bugs or bloat, such as `class`, `href`, `src`, `id` and other attributes, inside `<head>`, `<script>` or `<style>` contents, form values, or the page URL. Providing the callback opts in to the detection logic — when it isn't provided, no scanning runs.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  sanity: {
    visualEditing: {
      // ... Visual editing config
      onSuspiciousStega: (reports) => {
        for (const report of reports) {
          console.warn(`Stega found in ${report.kind}`, report)
        }
      },
    }
  },
})
```

Each report includes the offending `element`, the `attribute` name (when applicable), the raw `value`, the `cleaned` value it should have been, and the decoded `sanity` edit info when available — pointing at the exact document and field that produced the value.

#### `refresh`

- Type: **function**

An optional function for overriding the default handling of refresh events received from the studio. This is generally not need needed if the `mode` option is set to `live-visual-editing`.

#### `zIndex`

- Type: **number**, **string**
- Default: **9999999**

The CSS z-index on the root node that renders overlays.

### Recommended Configuration

For most use cases, the following minimum `visualEditing` configuration will suffice:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    // ... Sanity config
    visualEditing: {
      token: process.env.NUXT_SANITY_VISUAL_EDITING_TOKEN,
      studioUrl: process.env.NUXT_SANITY_VISUAL_EDITING_STUDIO_URL,
    }
  },
})
```


# Live Content

The Live Content API allows your app to subscribe to changes in your Sanity dataset and receive updates whenever documents are created, updated, or deleted.

This is ideal for fast-moving content like news, sports, or commerce.

::warning
Requires Sanity API version 

`v2021-03-25`

 or later.
::

## Usage

When live content is enabled in your Nuxt config, the module will automatically handle subscribing to live updates for you. You do **not** need to manually subscribe to events or use a custom composable.

### Install Sanity Client

Make sure you have the latest `@sanity/client`:

```bash
pnpm add @sanity/client
```

### Enable Live Content

Configure your Nuxt module to enable live content:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    projectId: '<your-project-id>',
    dataset: '<your-dataset>',
    apiVersion: '2021-03-25',
    liveContent: {
      browserToken: process.env.NUXT_SANITY_LIVE_BROWSER_TOKEN,
      serverToken: process.env.NUXT_SANITY_LIVE_SERVER_TOKEN,
    },
  },
})
```

### Querying Live Content

Use the built-in `useSanityQuery` composable. Live updates are handled automatically — no need to manually subscribe or use a custom composable.

```ts
<script setup lang="ts">
const { data, refresh, pending, error } = useSanityQuery(
  '*[_type == "post"] | order(_createdAt desc)'
)
</script>

<template>
  <div v-if="data">
    <div v-for="post in data" :key="post._id">
      <h2>{{ post.title }}</h2>
      <p>{{ post.body }}</p>
    </div>
  </div>
</template>
```

- `data` is a ref that will update automatically when content changes in Sanity.
- `refresh` can be called to manually re-fetch.
- `pending` and `error` are also available.

## Advanced: Manual Live Mode Control

If you need to manually enable or disable live mode (rare for most users), you can use the `useSanityLiveMode` composable:

```ts
<script setup>
const disable = useSanityLiveMode()
// Call disable() to turn off live mode if needed
</script>
```

## Resources

- [Sanity Live Content API Docs](https://www.sanity.io/docs/content-lake/live-content-api){rel="&#x22;nofollow&#x22;"}
- [Live Content API Reference](https://www.sanity.io/docs/http-reference/live){rel="&#x22;nofollow&#x22;"}
- [Live Content Examples on GitHub](https://github.com/sanity-io/lcapi-examples){rel="&#x22;nofollow&#x22;"}


# Typegen

`@nuxtjs/sanity` supports automatic TypeScript type generation for your GROQ queries using [`@sanity/codegen`](https://github.com/sanity-io/sanity/tree/next/packages/@sanity/codegen){rel="&#x22;nofollow&#x22;"}. This enables end-to-end type safety from your Sanity schema to your Vue components.

## Setup

### Prerequisites

Your project must have a Sanity schema types file that exports an array of schema type definitions. This is typically located at `cms/schemaTypes/index.ts`:

```ts [cms/schemaTypes/index.ts]
import { movie } from './movie'
import { person } from './person'

export const schemaTypes = [movie, person]
```

### Configuration

Enable type generation in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/sanity'],
  sanity: {
    projectId: 'your-project-id',
    typegen: {
      enabled: true,
      schemaTypesPath: './cms/schemaTypes',
    },
  },
})
```

## Usage

Once configured, types are automatically generated during `nuxt prepare` and whenever schema or query files change in development mode.

### Writing Queries

Use the `groq` template tag to write your queries. Generated types follow a naming convention based on your query variable name:

```vue
<script setup lang="ts">
// Query variable: moviesQuery -> Generated type: MoviesQueryResult
const moviesQuery = groq`*[_type == "movie"] { title, slug }`

// Use the generated type for full type safety
const { data } = await useSanityQuery<MoviesQueryResult>(moviesQuery)
</script>
```

### Using `defineQuery`

For better editor support and explicit query definition, you can use `defineQuery`:

```vue
<script setup lang="ts">
const moviesQuery = defineQuery(`*[_type == "movie"] { title, slug }`)

const { data } = await useSanityQuery<MoviesQueryResult>(moviesQuery)
</script>
```

Both `groq` and `defineQuery` are auto-imported and available throughout your application.

### Generated Types

The module generates types based on your query variable names:

| Query Variable     | Generated Type           |
| ------------------ | ------------------------ |
| `moviesQuery`      | `MoviesQueryResult`      |
| `movieBySlugQuery` | `MovieBySlugQueryResult` |
| `allPostsQuery`    | `AllPostsQueryResult`    |

These types are automatically available via auto-imports - no manual import statements required.

### Server Routes

Type generation also works in your Nitro server routes:

```ts [server/api/movies.ts]
export default defineEventHandler(async () => {
  const sanity = useSanity()
  const query = groq`*[_type == "movie"] { title }`
  
  return sanity.fetch<FetchMoviesQueryResult>(query)
})
```

## Configuration Options

### `typegen.enabled`

- Type: **boolean**
- Default: &#x2A;*`false`**

Enable or disable type generation.

### `typegen.schemaTypesPath`

- Type: **string**
- Required when `enabled` is `true`

Path to your schema types module. This should be a file that exports an array of Sanity schema type definitions.

### `typegen.schemaTypesExport`

- Type: **string**
- Default: &#x2A;*`'schemaTypes'`**

The export name to read schema types from. By default, the module looks for a named export called `schemaTypes`, or falls back to the default export.

### `typegen.queryPaths`

- Type: &#x2A;*string | string []**
- Default: &#x2A;*`['**/*.{ts,tsx,js,jsx,mjs,cjs,vue,astro}']`** (relative to `srcDir`)

Glob pattern(s) specifying which files to scan for GROQ queries.

### `typegen.overloadClientMethods`

- Type: **boolean**
- Default: &#x2A;*`true`**

When enabled, generates `@sanity/client` method overloads that provide type inference for the `fetch` method.

## Current Limitations

::callout{type="info"}
Currently, you must manually specify the result type in composables (e.g., 

`useSanityQuery<MoviesQueryResult>`

). This is because 

`@sanity/codegen`

 checks for explicit imports of 

`groq`

 or 

`defineQuery`

, but Nuxt uses auto-imports. Automatic type inference based on the query variable may be supported in a future update to 

`@sanity/codegen`

.
::

## File Watching

In development mode, the module watches for changes to:

- Your schema types file (`schemaTypesPath`)
- Any files matching `queryPaths` patterns

Types are automatically regenerated when these files change.


# Portable Text

## Global helper

This module defines a global `<SanityContent>` component that can turn [portable text](https://www.sanity.io/guides/beginners-guide-to-portable-text){rel="&#x22;nofollow&#x22;"} into HTML. It is a lightweight functional component without an instance.

As of v2, `<SanityContent>` uses [`@portabletext/vue`](https://github.com/portabletext/vue-portabletext){rel="&#x22;nofollow&#x22;"} for rendering portable text. This means features and properties available to `@portabletext/vue` also work with `<SanityContent>`. Please refer to their [Usage guide](https://github.com/portabletext/vue-portabletext?tab=readme-ov-file#basic-usage){rel="&#x22;nofollow&#x22;"} for advanced configuration options.

::warning
This render change introduces **breaking changes** for `<SanityContent>` v2 components. Refer to the following upgrade guide:

- To reflect `@portabletext/vue`'s props, `blocks` → `value` and `serializers` → `components` attribute name changes have been made. The property types remain the same.
- Custom components now receive their data nested within a `props.value` object. When defining components, you need to extract your props from this structure using object spreading: `{...props.value}`. This applies to all component types (blocks, marks, styles).
::

### Example

```vue
<template>
  <SanityContent :value="content" />
</template>
```

### Image handling

The `<SanityContent>` component automatically handles Sanity images using the `<SanityImage>` component, which will use `<NuxtImg>` if `@nuxt/image` is installed.

The default image component supports:

- **Asset ID**: Extracted from the image block and passed to `<SanityImage>`
- **Hotspot**: Converted to focal point coordinates (`fp-x`, `fp-y`) for proper cropping
- **Crop**: Converted to a `rect` parameter using the image dimensions from the asset ID

Custom fields like `caption` and `attribution` are not rendered by the default component. If you need to display captions or other custom data, provide a custom image component as shown below.

### Example with custom components

```vue
<template>
  <SanityContent :value="content" :components="components" />
</template>

<script setup>
import { defineAsyncComponent, h, resolveComponent } from 'vue'
import CustomBlockComponent from '~/components/CustomBlockComponent.vue'

const components = {
  types: {
    // This is how to access a component registered by `@nuxt/components`
    lazyRegisteredComponent: props => h(resolveComponent('LazyCustomSerializer'), {
      ...props.value,
    }),
    // A directly imported component
    importedComponent: props => h(CustomBlockComponent, {
      ...props.value,
    }),
    // Example of a more complex async component
    dynamicComponent: props => h(defineAsyncComponent({
      loadingComponent: () => 'Loading...',
      loader: () => import('~/other/component.vue'),
    }), {
      ...props.value,
    }),
    // You can override the default image component if needed
    image: props => h('CustomImageComponent', {
      ...props.value,
    }),
    // Example of handling caption and attribution in a custom component
    imageWithCaption: props => {
      const { asset, caption, attribution, crop, hotspot } = props.value
      return h('div', { class: 'custom-image-wrapper' }, [
        h('img', { src: `https://cdn.sanity.io/images/.../${asset._ref}` }),
        caption && h('p', { class: 'caption' }, caption),
        attribution && h('p', { class: 'attribution' }, attribution)
      ])
    },
  },
  marks: {
    // Custom marks handling
    internalLink: props => h('a', { href: props.value.href }, props.text)
  }
}
</script>
```

### Image Block Structure

The automatic image handling works with the standard Sanity portable text image block structure:

```json
{
  "_type": "image",
  "asset": {
    "_type": "reference",
    "_ref": "image-61991cfbe9182124c18ee1829c07910faadd100e-2048x1366-png"
  },
  "caption": "This is the caption (ignored by default component)",
  "attribution": "Public domain (ignored by default component)",
  "crop": {
    "top": 0.028131868131868132,
    "bottom": 0.15003663003663004,
    "left": 0.01875,
    "right": 0.009375000000000022
  },
  "hotspot": {
    "x": 0.812500000000001,
    "y": 0.27963369963369955,
    "height": 0.3248351648351647,
    "width": 0.28124999999999994
  }
}
```

The component automatically:

1. Extracts the `_ref` from the asset object and passes it as `assetId` to `<SanityImage>`
2. Converts `hotspot.x` and `hotspot.y` to `fp-x` and `fp-y` focal point parameters
3. Calculates the `rect` parameter from the `crop` object using the original image dimensions (parsed from the asset ID)

Caption and attribution fields are ignored by the default component. Use a custom image component if you need to render these.

### Disabling Default Image Handling

If you want to handle images yourself or disable the automatic image handling entirely, you can use the `disableDefaultImageComponent` prop:

```vue
<template>
  <!-- Disable automatic image handling -->
  <SanityContent 
    :value="content" 
    disable-default-image-component
  />
  
  <!-- Or provide your own image component -->
  <SanityContent 
    :value="content" 
    disable-default-image-component
    :components="{
      types: {
        image: props => h('MyCustomImage', {
          assetId: props.value.asset._ref,
          caption: props.value.caption
        })
      }
    }"
  />
</template>
```

When `disableDefaultImageComponent` is set to `true`, the component will not automatically handle image blocks. If you don't provide your own image component in the `components.types.image` prop, PortableText will show a warning about the missing component.

::warning
If you want to use the same components in multiple places, consider creating your own component (e.g. 

`<MySanityContent>`

) which wraps SanityContent with your default components. By creating 

`~/components/MySanityContent.vue`

 you should be able to use this everywhere in your app without importing it.
::

### Advanced Props

The `SanityContent` component accepts all props from `@portabletext/vue`:

```vue
<template>
  <SanityContent 
    :value="content" 
    :components="components"
    :onMissingComponent="handleMissingComponent"
    :listNestingMode="'html'" 
  />
</template>

<script setup>
const handleMissingComponent = (message, options) => {
  console.warn(`Missing component: ${options.type} (${options.nodeType})`)
}
</script>
```

### TypeScript Support

All types from `@portabletext/vue` and `@portabletext/types` are re-exported from `@nuxtjs/sanity`:

```vue
<script setup lang="ts">
import type { PortableTextComponents } from '@nuxtjs/sanity/runtime/types'
import { defineAsyncComponent, h } from 'vue'
import CustomBlockComponent from '~/components/CustomBlockComponent.vue'

const components: PortableTextComponents = {
  types: {
    customBlock: props => h(CustomBlockComponent, {
      ...props.value,
    }),
  },
  marks: {
    link: props => h('a', {
      href: props.value.href,
      target: '_blank'
    }, props.text)
  }
}
</script>

<template>
  <SanityContent :value="content" :components="components" />
</template>
```

## Other resources

- [@portabletext/vue](https://github.com/portabletext/vue-portabletext){.text-primary-500 rel="&#x22;nofollow&#x22;"}


# Images

## `<SanityImage>`

This module provides a global `<SanityImage>` component to assist with rendering images from Sanity.

By default, it is a lightweight functional component that turns the given props into a valid image URL. However, if you have [`@nuxt/image`](https://image.nuxt.com/){rel="&#x22;nofollow&#x22;"} installed, it will automatically use `<NuxtImg>` for improved performance.

### Nuxt Image Integration

When `@nuxt/image` is installed in your project, `<SanityImage>` will automatically detect it and render a `<NuxtImg>` component instead of a regular `<img>` tag. This allows you to leverage the powerful features of Nuxt Image, such as resizing, format conversion, and optimizations.

To enable the Sanity provider within Nuxt Image, you need to configure it in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    sanity: {
      projectId: 'your-project-id',
      dataset: 'your-dataset-name'
    }
  },

  sanity: {
    // module options
  }
})
```

You can use `<SanityImage>` with the same props as before. Sanity image transformation props (like `w`, `h`, `auto`, `fit`, etc.) are passed to `<NuxtImg>` as modifiers for the Sanity provider, while other attributes (like `class`, `alt`, `loading`) are passed through directly.

```vue
<template>
  <!-- This will render a <NuxtImg> component -->
  <SanityImage
    asset-id="image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg"
    w="300"
    h="450"
    auto="format"
  />
</template>
```

### Basic Usage

If you are not using `@nuxt/image`, `<SanityImage>` will generate a standard `<img>` tag.

#### Props

##### `assetId`

The Sanity asset ID, which has the format `image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg`.

- Type: **string**
- **Required**

##### `projectId` and `dataset`

These default to the `projectId` and `dataset` from the module options, but can be overridden as props.

- Type: **string**

##### Image transformation props

All other image transformation options from the [Sanity documentation](https://www.sanity.io/docs/image-urls){rel="&#x22;nofollow&#x22;"} are also valid props.

#### Example

```vue
<template>
  <SanityImage
    asset-id="image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg"
    auto="format"
  />
</template>
```

## Renderless Usage

By passing a default scoped slot, you can use the `<SanityImage>` component in a renderless fashion to take full control of the rendered markup.

### Example

```vue
<template>
  <SanityImage
    asset-id="image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg"
    auto="format"
  >
    <template #default="{ src }">
      <img :src="src" />
    </template>
  </SanityImage>
</template>
```

## Using `@sanity/image-url`

If the `<SanityImage>` component does not cover your specific needs, you can use the official [`@sanity/image-url`](https://github.com/sanity-io/image-url){rel="&#x22;nofollow&#x22;"} package. One way to integrate it is through a Nuxt plugin:

```js [plugins/sanity-image-builder.js]
import imageUrlBuilder from '@sanity/image-url'

export default defineNuxtPlugin(() => {
  const builder = imageUrlBuilder(useSanity().config)
  function urlFor(source) {
    return builder.image(source).auto('format')
  }
  return {
    provide: { urlFor }
  }
})
```

This will provide a global `$urlFor` helper that you can use in your templates:

```vue
<template>
  <img
    :src="$urlFor(movie.image).size(426).url()"
    :alt="movie.title"
    height="426"
    width="426"
    loading="lazy"
  />
</template>
```


# Files

## Global helper

This module defines a global `<SanityFile>` component to assist with auto-generating your file URLs. It is a lightweight functional component that simply turns the props into a valid file URL.

### Props

#### `assetId`

The Sanity asset ID (of the form `file-41773b5c55bc5414ab7554a75eefddf8e2e14524-txt`).

- Type: **string**
- **Required**

#### `projectId` and `dataset`

These default to the `projectId` and `dataset` passed into the module options but can be overridden.

- Type: **string**

#### `download`

- Type: **string** or **boolean**
- Default: `false`

If set, the URL will contain a download link to that asset. If set to a string, the file will download to that filename. Otherwise, the original filename will be used (if saved in Sanity). If the original filename is not available, the id of the file will be used instead. See [the Sanity documentation](https://www.sanity.io/docs/file-type){rel="&#x22;nofollow&#x22;"}.

### Example

```vue
<template>
  <SanityFile asset-id="file-41773b5c55bc5414ab7554a75eefddf8e2e14524-txt" download="myfile.txt">
    <template #default="{ src }">
      <a :href="src">Click here to read this text file</a>
    </template>
  </SanityFile>
</template>
```


# Groq

This module exports the official [`groq`](https://github.com/sanity-io/groq){rel="&#x22;nofollow&#x22;"} template tag function for writing GROQ queries with syntax highlighting. Make sure to install [the VSCode extension](https://github.com/sanity-io/vscode-sanity){rel="&#x22;nofollow&#x22;"} for the best experience.

Both `groq` and `defineQuery` are globally available throughout your project (in server routes and Vue components) via auto-imports.

## `groq`

Use the `groq` template tag to write your GROQ queries:

```vue
<script setup>
// In VS Code this will be highlighted
const query = groq`*[_type == "article"][0].title`
</script>
```

## `defineQuery`

The `defineQuery` function provides an alternative way to define queries using a regular function call instead of a template tag:

```vue
<script setup>
const query = defineQuery(`*[_type == "article"][0].title`)
</script>
```

Both produce identical results. `defineQuery` is particularly useful when working with [type generation](sanity.nuxtjs.org/getting-started/typegen), as the `@sanity/codegen` tool recognizes both patterns when scanning for queries.

## Type Generation

When [type generation](sanity.nuxtjs.org/getting-started/typegen) is enabled, queries written with `groq` or `defineQuery` are automatically discovered and typed. The generated types follow a naming convention based on your query variable name:

```vue
<script setup lang="ts">
// Query variable: articlesQuery -> Generated type: ArticlesQueryResult
const articlesQuery = groq`*[_type == "article"] { title, slug }`

const { data } = await useSanityQuery<ArticlesQueryResult>(articlesQuery)
// data is typed as Ref<{ title: string; slug: { current: string } }[] | null>
</script>
```


# Visual Editing

When visual editing is enabled, this module exports a `createSanityDataAttribute` helper function which allows you to manually map content in a component to its source.

It is globally available throughout your project (both within your server routes and your Vue app) via auto-imports.

See the [Sanity documentation](https://www.sanity.io/docs/visual-editing-overlays#cb95b19a0263){rel="&#x22;nofollow&#x22;"} for more information.

## Example

```vue
<template>
  <h1 :data-sanity="createSanityDataAttribute({
    id: 'the-godfather',
    type: 'movie',
    path: 'title',
  })">The Godfather</h1>
</template>
```


# Credits

Thanks to the following projects:

- [groq](https://github.com/sanity-io/sanity/tree/next/packages/groq){.text-primary-500 rel="&#x22;nofollow&#x22;"}
- [nuxt-sanity](https://github.com/vicbergquist/nuxt-sanity){.text-primary-500 rel="&#x22;nofollow&#x22;"}
- [picosanity](https://github.com/rexxars/picosanity){.text-primary-500 rel="&#x22;nofollow&#x22;"}
- [sanity-blocks-vue-component](https://github.com/rdunk/sanity-blocks-vue-component){.text-primary-500 rel="&#x22;nofollow&#x22;"}


# Changelog

Discover the latest updates.

---

::warning
- This page is work in progress.
- [Visit this page](https://github.com/nuxt-modules/sanity/releases){rel=""nofollow""}
::


# Nuxt Sanity

::u-page-hero
#title
Nuxt Sanity

#description
The easiest way to use Sanity with Nuxt. Get up and running in minutes with a lightweight client, zero-config components, and a great developer experience.

#links
  :::u-button
  ---
  color: neutral
  size: xl
  to: sanity.nuxtjs.org/getting-started/installation
  trailing-icon: i-lucide-arrow-right
  ---
  Get started
  :::

:copy-code-input{source="npx nuxi@latest module add sanity"}

  :::u-page-section
  #title
  Everything you need for your Nuxt project

  #features
  :u-page-feature{icon="i-simple-icons-sanity"}

  #title
  Zero-config setup

  #description
  Just bring your `sanity.config.ts` and you're good to go. No extra configuration needed.
  \:::

  :u-page-feature{icon="i-lucide-zap"}

  #title
  Lightweight client

  #description
  A super light client to fetch your content without slowing down your site.
  \:::

  :u-page-feature{icon="i-lucide-image"}

  #title
  Components ready to use

  #description
  Image and file components that work out of the box, including a renderer for your Portable Text.
  \:::

  :u-page-feature{icon="i-ph-eye-bold"}

  #title
  Live Previews & Visual Editing

  #description
  See your content changes live and jump straight from your site to the right spot in your Sanity Studio.
  \:::

  :u-page-feature{icon="i-ph-file-code-bold"}

  #title
  GROQ and TypeScript

  #description
  Write your GROQ queries with syntax highlighting and get full type-safety for your data.
  \:::
  :::
::