---
url: https://s00d.github.io/nuxt-i18n-micro/composables/useLocaleHead.md
description: SEO meta tags and head attrs for localized routes.
---

# 🌍 `useLocaleHead` Composable

The `useLocaleHead` composable is a utility in `Nuxt I18n Micro` that helps you manage SEO attributes and HTML meta tags for localized routes. It dynamically generates attributes for the `lang` and `dir` of the HTML document and creates `meta` and `link` tags to improve the SEO of your localized content.

## ⚙️ Options

```ts
useLocaleHead(options: UseLocaleHeadOptions): { metaObject: Ref<{ htmlAttrs: { dir?: "ltr" | "rtl" | "auto"; lang?: string }; link: { href: string; hreflang?: string; rel: string; [key: string]: string | undefined }[]; meta: { content: string; property: string; [key: string]: string }[] }, MetaObject | { htmlAttrs: { dir?: "ltr" | "rtl" | "auto"; lang?: string }; link: { href: string; hreflang?: string; rel: string; [key: string]: string | undefined }[]; meta: { content: string; property: string; [key: string]: string }[] }>; updateMeta: () => void }
```

The SEO head tags for the current route: `hreflang` alternates for every locale plus
`x-default`, a canonical link, `og:locale`, and `lang`/`dir` on `<html>`.

Only needed when `meta` is disabled or the defaults need adjusting — with `meta: true`
the module registers the same tags itself.

| Parameter | Type | Description |
| --- | --- | --- |
| `options` | `UseLocaleHeadOptions` |  |

**Returns** — a ref holding the head object, ready to pass to `useHead`

```ts
const head = useLocaleHead({ addSeoAttributes: true })
useHead(head)
```

## 🛠️ Return Values

The `useLocaleHead` composable returns a reactive object and an updater function you should
call when source data changes. Both shapes are in the signature above, generated from the
source.

### `metaObject`

Reactive head payload (html attrs, meta, link) suitable for `useHead(metaObject)`.

* **Example**:
  ```js
  const { metaObject } = useLocaleHead()
  useHead(metaObject)
  ```

### `updateMeta`

Recomputes `metaObject` based on current route, locale and config. With
`autoUpdate: true` (default for manual usage) this runs on route **and** locale
changes. With `autoUpdate: false` (used by `02.meta`), call it yourself when
inputs change.

* **Example**:
  ```js
  const { metaObject, updateMeta } = useLocaleHead()
  useHead(metaObject)
  watch(
    () => route.fullPath,
    () => updateMeta(),
    { immediate: true },
  )
  ```

### Accessing `link` and `meta`

The `link` and `meta` arrays are accessible via `metaObject.value`:

* **Example**:
  ```js
  const { metaObject, updateMeta } = useLocaleHead()
  updateMeta()
  console.log(metaObject.value.link)
  // Output: [{ id: 'i18n-can', rel: 'canonical', href: 'https://example.com/about' }, ...]
  console.log(metaObject.value.meta)
  // Output: [{ id: 'i18n-og', property: 'og:locale', content: 'en_US' }, ...]
  ```

## 🛠️ Example Usages

### Basic Usage

Generate locale-specific head attributes with default options.

```js
const head = useLocaleHead()
```

### Customize Identifier Attribute

Use a custom identifier attribute for the generated tags.

```js
const head = useLocaleHead({ identifierAttribute: 'data-i18n' })
```

### Disable SEO Attributes

Generate head attributes without adding SEO-related meta and link tags.

```js
const head = useLocaleHead({ addSeoAttributes: false })
```

### Specify a Base URL

Set a custom base URL for canonical and alternate URLs.

```js
const head = useLocaleHead({ baseUrl: 'https://mywebsite.com' })
```

## 🚀 Additional Features

### SEO Meta and Link Tags

When `addSeoAttributes` is enabled, the composable automatically generates the following tags:

* `og:locale` for the current locale (`language_TERRITORY`, underscore). Derived from `locale.og` or converted from `locale.iso` when possible.
* `og:url` for the canonical URL of the page.
* `og:locale:alternate` for alternate language versions.
* `rel="canonical"` and `rel="alternate"` links for SEO optimization.
* `hreflang="x-default"` link pointing to the default locale's URL. This tells search engines which URL to show users whose language doesn't match any of the defined locales.

### Dynamic Locale and Direction

The composable dynamically determines the `lang` and `dir` attributes based on the current route's locale, ensuring that your HTML document is correctly configured for international users.

### Handling Localized Routes

If your routes are prefixed with locale codes (e.g., `/en/about`), the composable intelligently adjusts the full path for generating URLs, ensuring that SEO attributes are accurate and relevant.

This composable simplifies the process of optimizing your Nuxt application for international audiences, ensuring that your site is well-prepared for global search engines and users.

## 🛠️ Example Usage

The following example demonstrates how to use the `useLocaleHead` composable within a Vue component with default settings:

```vue
<script setup>
import { useRoute, watch } from '#imports'
const route = useRoute()
const { metaObject, updateMeta } = useLocaleHead({
  addDirAttribute: true,
  identifierAttribute: 'id',
  addSeoAttributes: true,
})
useHead(metaObject)
watch(
  () => route.fullPath,
  () => updateMeta(),
  { immediate: true },
)
</script>
```

### Explanation of the Code

* **`useLocaleHead` Composable**: This composable is called in the `<script setup>` section and returns an object containing `htmlAttrs`, `meta`, and `link`.

* **`<html>` Tag**: The `lang` and `dir` attributes for the HTML document are dynamically determined based on the current locale and are applied to the `<html>` tag.

* **`<head>` Section**:
  * **Meta Tags**: SEO-related meta tags are generated, including `og:locale`, `og:url`, and `rel="canonical"` and `rel="alternate"` tags to specify alternate language versions of the page.
  * **Link Tags**: Canonical links, links to alternate language versions, and the `hreflang="x-default"` link (pointing to the default locale URL) are included.

* **`<body>` Section**: The main content of the page is displayed here. In this example, a simple header and paragraph are used.

### 📝 Notes

1. **Attributes**: The attributes used (`lang`, `dir`, `rel`, `href`, `hreflang`, `property`, `content`) are extracted from the object returned by `useLocaleHead`.

2. **SEO Tags Generation**: If the `addSeoAttributes` option is set to `true`, the composable automatically generates SEO tags for the current locale.

3. **Base URL**: You can set your custom base URL using the `baseUrl` option to correctly generate canonical and alternate links.

This example demonstrates how easy it is to integrate `useLocaleHead` into your application's components to ensure correct SEO attributes and improve the search engine indexing of localized pages.

## 🧩 Customization & Lifecycle

* With `autoUpdate: true` (default), `useLocaleHead` watches the route and `i18n-locale` state and refreshes `metaObject`.
* With `autoUpdate: false` (what `02.meta` uses), call `updateMeta()` yourself when inputs change:

```ts
// plugins/02.meta.ts
export default defineNuxtPlugin(() => {
  const route = useRoute()
  const localeState = useState<string | null>('i18n-locale', () => null)
  const { metaObject, updateMeta } = useLocaleHead({ baseUrl: 'https://example.com', autoUpdate: false })
  useHead(metaObject)
  if (import.meta.server) updateMeta()
  else
    watch(
      () => [route.fullPath, localeState.value] as const,
      () => updateMeta(),
      { immediate: true },
    )
})
```

## When to use `useI18nHead` instead

When `meta: true` (the default), prefer [`useI18nHead`](/composables/useI18nHead) for **per-page** overrides (custom hreflang, extra `og:title`, partial disable). Use `useLocaleHead` directly only when `meta: false` or you manage `useHead` yourself.