useSeoMeta Transform · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview)
- [Tools](https://unhead.unjs.io/tools)
- [Learn](https://unhead.unjs.io/learn/guides/what-is-capo)

[Releases](https://unhead.unjs.io/releases)

Search…```k`` /`

[Unhead on GitHub](https://github.com/unjs/unhead)

[User Guides](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/typescript/head/api/get-started/overview)

[Releases](https://unhead.unjs.io/docs/typescript/releases/v3)

TypeScript

- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/guides/build-plugins/seo-meta-transform)
- [Switch to Vue](https://unhead.unjs.io/docs/vue/head/guides/build-plugins/seo-meta-transform)
- [Switch to React](https://unhead.unjs.io/docs/react/head/guides/build-plugins/seo-meta-transform)
- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/guides/build-plugins/seo-meta-transform)
- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/guides/build-plugins/seo-meta-transform)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/head/guides/build-plugins/seo-meta-transform)
- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/guides/build-plugins/seo-meta-transform)

v3 (stable)

Head

- [Discord Support](https://discord.com/invite/275MBUBvgP)
- [TypeScript Playground](https://stackblitz.com/edit/github-hhxywsb5)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview)
  - [Introduction to Unhead](https://unhead.unjs.io/docs/typescript/head/guides/get-started/intro-to-unhead)
  - [Starter Recipes](https://unhead.unjs.io/docs/typescript/head/guides/get-started/starter-recipes)
- Core Concepts
  - [Titles & Title Templates](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/titles)
  - [Tag Sorting & Placement](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/positions)
  - [Class & Style Attributes](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/class-attr)
  - [Inline Style & Scripts](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/inner-content)
  - [Tag Deduplication](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/handling-duplicates)
  - [DOM Event Handling](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/dom-event-handling)
  - [Script Loading](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/loading-scripts)
- Build Plugins
  - [Overview](https://unhead.unjs.io/docs/typescript/head/guides/build-plugins/overview)
  - [Tree-Shaking](https://unhead.unjs.io/docs/typescript/head/guides/build-plugins/tree-shaking)
  - [useSeoMeta Transform](https://unhead.unjs.io/docs/typescript/head/guides/build-plugins/seo-meta-transform)
  - [Minify Transform](https://unhead.unjs.io/docs/typescript/head/guides/build-plugins/minify-transform)
  - [Devtools](https://unhead.unjs.io/docs/typescript/head/guides/build-plugins/devtools)
- Plugins
  - [Template Params](https://unhead.unjs.io/docs/typescript/head/guides/plugins/template-params)
  - [Alias Sorting](https://unhead.unjs.io/docs/typescript/head/guides/plugins/alias-sorting)
  - [Canonical Plugin](https://unhead.unjs.io/docs/typescript/head/guides/plugins/canonical)
  - [Infer SEO Meta](https://unhead.unjs.io/docs/typescript/head/guides/plugins/infer-seo-meta-tags)
  - [Minify](https://unhead.unjs.io/docs/typescript/head/guides/plugins/minify)
  - [Validate](https://unhead.unjs.io/docs/typescript/head/guides/plugins/validate)

Build Plugins

# useSeoMeta Transform

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/build-plugins/2.seo-meta-transform.md)

Last updated Apr 9, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [refactor(bundler)!: named Unhead export, ctx-based transforms, dev-mode validate (#733)](https://github.com/unjs/unhead/pull/733).

On this page

- [What Does It Do?](#what-does-it-do)
- [Setup](#setup)
- [Options](#options)
- [Limitations](#limitations)

**Quick Answer:** The `useSeoMeta` transform rewrites `useSeoMeta()` calls into equivalent `useHead()` calls at build time. This removes the runtime meta-key resolution code (~3kb) from your bundle. Enabled by default. Also handles the deprecated `useServerSeoMeta()` for legacy code.

## [What Does It Do?](#what-does-it-do)

At build time, `useSeoMeta()` calls with static or semi-static arguments are converted to `useHead()` with pre-resolved `meta` arrays:

Before (source)

After (build output)

```
useSeoMeta(unheadInstance, {
  title: 'My Title',
  description: 'My Description',
  ogImage: 'https://example.com/image.png',
})
```

```
useHead(unheadInstance, {
  title: 'My Title',
  meta: [
    { name: 'description', content: 'My Description' },
    { property: 'og:image', content: 'https://example.com/image.png' },
  ],
})
```

Import specifiers are also rewritten: `import { useSeoMeta } from 'unhead'` becomes `import { useHead } from 'unhead'`.

## [Setup](#setup)

The transform is enabled by default when using the [unified Vite plugin](https://unhead.unjs.io/docs/head/guides/build-plugins/overview):

```
import { Unhead } from '@unhead/vue/vite'

export default defineConfig({
  plugins: [Unhead()],
})
```

### [Disable](#disable)

```
Unhead({
  transformSeoMeta: false,
})
```

## [Options](#options)

```
Unhead({
  transformSeoMeta: {
    // Disable import specifier rewriting
    imports: false,
    // Extra import paths to recognize as useSeoMeta sources
    importPaths: ['my-custom-package'],
    // Override the shared file filter
    filter: {
      include: [/my-special-file/],
      exclude: [/some-file/],
    },
  },
})
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `imports` | `boolean` | `true` | Rewrite import specifiers (`useSeoMeta` → `useHead`) |
| `importPaths` | `string[]` | — | Additional package names to treat as valid `useSeoMeta` sources |
| `filter` | `object` | inherited | Include/exclude file patterns (overrides the shared `filter`) |

## [Limitations](#limitations)

The transform skips calls it cannot statically analyze:

- Spread elements in the options object (`useSeoMeta({ ...dynamicMeta })`)
- Non-identifier keys
- Properties with missing values
- Object-valued properties with non-static (non-string-literal) sub-properties

In these cases, the original `useSeoMeta()` call is preserved and resolved at runtime.

### [Deprecated `useServerSeoMeta`](#deprecated-useserverseometa)

The transform also handles the deprecated `useServerSeoMeta()`. When it includes `title` or `titleTemplate`, the transform splits the call into two: a `useHead()` call for the title fields and a `useServerHead()` call for the meta tags.

```
// Input (deprecated)
useServerSeoMeta({ title: 'My Title', description: 'My Desc' })

// Output
useHead(unheadInstance, { title: 'My Title' });
useServerHead(unheadInstance, { meta: [{ name: 'description', content: 'My Desc' }] })
```

New code should use `useSeoMeta()` instead.

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/1.guides/build-plugins/2.seo-meta-transform.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/build-plugins/2.seo-meta-transform.md)

Did this page help you?

[Tree-Shaking Automatically remove server-only composables from client bundles at build time.](https://unhead.unjs.io/docs/head/guides/build-plugins/tree-shaking) [Minify Transform Pre-minify static inline script and style content inside useHead() calls at build time using rolldown, esbuild, or lightningcss.](https://unhead.unjs.io/docs/head/guides/build-plugins/minify-transform)

On this page

- [What Does It Do?](#what-does-it-do)
- [Setup](#setup)
- [Options](#options)
- [Limitations](#limitations)

[GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP)

[ /llms.txt](https://unhead.unjs.io/llms.txt)

[Part of the UnJS ecosystem](https://unjs.io/)

### Head Management

- [Getting Started](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script)

### Schema.org

- [Getting Started](https://unhead.unjs.io/docs/typescript/schema-org/guides/get-started/overview)
- [useSchemaOrg](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org)
- [Nodes](https://unhead.unjs.io/docs/typescript/schema-org/guides/core-concepts/nodes)
- [Recipes](https://unhead.unjs.io/docs/typescript/schema-org/guides/recipes/identity)

### Guides

- [Titles](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/typescript/head/guides/plugins/template-params)

### Tools

- [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator)
- [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator)
- [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator)
- [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer)

### Articles

- [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo)

### Research

- [State of <head> in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026)
- [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance)
- [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research)

Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)