<commit_before>---
title: Gatsby Head API
examples:
  - label: Using Gatsby Head
    href: "https://github.com/gatsbyjs/gatsby/tree/master/examples/using-gatsby-head"
---

> Support for the Gatsby Head API was added in `gatsby@4.19.0`.

Gatsby includes a built-in `Head` export that allows you to add elements to the [document head](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) of your pages.

Compared to [react-helmet](https://github.com/nfl/react-helmet) or other similar solutions, Gatsby Head is easier to use, more performant, has a smaller bundle size, and supports the latest React features.

## Using Gatsby Head in your page

By exporting a named function called `Head` you can set the metadata for a page:

```jsx:title=src/pages/index.jsx
import * as React from "react"

const Page = () => <div>Hello World</div>
export default Page

export function Head() {
  return (
    <title>Hello World</title>
  )
}
```

The arrow function syntax is also valid:

```jsx
export const Head = () => <title>Hello World</title>
```

When defining multiple metatags use React Fragments:

```jsx
export const Head = () => (
  <>
    <title>Hello World</title>
    <meta name="description" content="Hello World" />
  </>
)
```

You can also re-export a `Head` function in your page from another file:

```jsx:title=src/pages/index.jsx
import * as React from "react"

const Page = () => <div>Hello World</div>
export default Page

// highlight-next-line
export { Head } from "../another/location"
```

### Deduplication

To avoid duplicate tags in your `<head>` you can use the `id` property on your tags to make sure that only one is rendered. Given the following example:

```jsx
const SEO = ({ children }) => (
  <>
    <title>Hello World</title>
    <link id="icon" rel="icon" href="global-icon" />
    {children}
  </>
)

export const Head = () => (
  <SEO>
    <link id="icon" rel="icon" href="icon-specific-for-this-page" />
  </SEO>
)
```

In this case only the second `<link id="icon" rel="icon" href="icon-specific-for-this-page" />` is rendered. In a list of items with the same `id`, the last item wins and is used in the HTML.

### Usage notes

You'll need to be aware of these things when using Gatsby Head:

- You can only define the `Head` export inside a page, not in a component.
- The contents of Gatsby Head get cleared upon unmounting the page, so make sure that each page defines what it needs in its `<head>`.
- The `Head` function needs to return valid JSX.
- Valid tags inside the `Head` function are: `link`, `meta`, `style`, `title`, `base`, `script`, and `noscript`.
- Data block `<script>` tags such as `<script type="application/ld+json">` can go in the `Head` function, but dynamic scripts are better loaded with the [Gatsby Script Component](/docs/reference/built-in-components/gatsby-script/) in your pages or components.

## Properties

The `Head` function receives these properties:

- `location.pathname`: Returns the Location object's URL's path
- `params`: The URL parameters when the page has a `matchPath` (when using [client-only routes](/docs/how-to/routing/client-only-routes-and-user-authentication/))
- `data`: Data passed into the page via an exported GraphQL query
- `pageContext`: A context object which is passed in during the creation of the page

```jsx<commit_msg>chore(docs): Add `react-helmet` note in Gatsby Head reference (#36216)<commit_after>---
title: Gatsby Head API
examples:
  - label: Using Gatsby Head
    href: "https://github.com/gatsbyjs/gatsby/tree/master/examples/using-gatsby-head"
---

> Support for the Gatsby Head API was added in `gatsby@4.19.0`.

Gatsby includes a built-in `Head` export that allows you to add elements to the [document head](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) of your pages.

Compared to [react-helmet](https://github.com/nfl/react-helmet) or other similar solutions, Gatsby Head is easier to use, more performant, has a smaller bundle size, and supports the latest React features.

## Using Gatsby Head in your page

By exporting a named function called `Head` you can set the metadata for a page:

```jsx:title=src/pages/index.jsx
import * as React from "react"

const Page = () => <div>Hello World</div>
export default Page

export function Head() {
  return (
    <title>Hello World</title>
  )
}
```

The arrow function syntax is also valid:

```jsx
export const Head = () => <title>Hello World</title>
```

When defining multiple metatags use React Fragments:

```jsx
export const Head = () => (
  <>
    <title>Hello World</title>
    <meta name="description" content="Hello World" />
  </>
)
```

You can also re-export a `Head` function in your page from another file:

```jsx:title=src/pages/index.jsx
import * as React from "react"

const Page = () => <div>Hello World</div>
export default Page

// highlight-next-line
export { Head } from "../another/location"
```

### Deduplication

To avoid duplicate tags in your `<head>` you can use the `id` property on your tags to make sure that only one is rendered. Given the following example:

```jsx
const SEO = ({ children }) => (
  <>
    <title>Hello World</title>
    <link id="icon" rel="icon" href="global-icon" />
    {children}
  </>
)

export const Head = () => (
  <SEO>
    <link id="icon" rel="icon" href="icon-specific-for-this-page" />
  </SEO>
)
```

In this case only the second `<link id="icon" rel="icon" href="icon-specific-for-this-page" />` is rendered. In a list of items with the same `id`, the last item wins and is used in the HTML.

### Usage notes

You'll need to be aware of these things when using Gatsby Head:

- You can only define the `Head` export inside a page, not in a component.
- The contents of Gatsby Head get cleared upon unmounting the page, so make sure that each page defines what it needs in its `<head>`.
- The `Head` function needs to return valid JSX.
- Valid tags inside the `Head` function are: `link`, `meta`, `style`, `title`, `base`, `script`, and `noscript`.
- Data block `<script>` tags such as `<script type="application/ld+json">` can go in the `Head` function, but dynamic scripts are better loaded with the [Gatsby Script Component](/docs/reference/built-in-components/gatsby-script/) in your pages or components.
- Using the Head API and [react-helmet](https://github.com/nfl/react-helmet) in the same page is not supported as it can generate unexpected results.

## Properties

The `Head` function receives these properties:

- `location.pathname`: Returns the Location object's URL's path
- `params`: The URL parameters when the page has a `matchPath` (when using [client-only routes](/docs/how-to/routing/client-only-routes-and-user-authentication/))
- `data`: Data passed into the page via an exported GraphQL query
- `pageContext`: A context object which is passed in during the creation of the page

```jsx
{'fraction_non_alphanumeric': 0.1277494537509104, 'fraction_numerical': 0.0018936635105608157, 'mean_word_length': 4.015339663988312, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 69, 'https://': 7, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2491539', 'n_tokens_mistral': 2146, 'n_tokens_neox': 2084, 'n_words': 840}