Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(docs): Update Head API about <html> and <body> attributes #37491

Merged
merged 4 commits into from
Jan 25, 2023
Merged

chore(docs): Update Head API about <html> and <body> attributes #37491

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1ab14bd
update head component docs
pieh Jan 18, 2023
20a3c0d
update example
pieh Jan 18, 2023
5ea692d
minor copy updates
pieh Jan 18, 2023
906b27f
Apply suggestions from code review
pieh Jan 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions docs/docs/reference/built-in-components/gatsby-head.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,28 @@ export default Page
export { Head } from "../another/location"
```

### Editing `<html>` and `<body>`

> Support for editing `<html>` and `<body>` was added in `[email protected]`.

You can set `<html>` and `<body>` attributes:

```jsx
export function Head() {
return (
<>
<!-- highlight-start -->
<html lang="en">
<body className="my-body-class">
<!-- highlight-end -->
<title>Hello World</title>
</>
)
}
```

Gatsby will use provided attributes and inject them into resulting html.
marvinjude marked this conversation as resolved.
Show resolved Hide resolved

### 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:
Expand Down Expand Up @@ -87,6 +109,7 @@ You'll need to be aware of these things when using Gatsby Head:
- 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`.
- `html` and `body` tags defined in `Head` overwrite the attributes defined in [`onRenderBody`](/docs/reference/config-files/gatsby-ssr/#onRenderBody) (`setHtmlAttributes` and `setBodyAttributes`).
- 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.
- As of now, `Head` can't access [React Context](https://reactjs.org/docs/context.html) that you defined in the [`wrapRootElement` API](/docs/reference/config-files/gatsby-browser/#wrapRootElement).

Expand All @@ -112,18 +135,6 @@ export const Head = ({ location, params, data, pageContext }) => (
)
```

## Editing `<html>` and `<body>`

The scope of Gatsby Head is to modify the `<head>` portion of your pages. To edit other parts like `<html>` or `<body>`, please use the [Gatsby Server Rendering APIs](/docs/reference/config-files/gatsby-ssr/).

One common use case is to modify the `<html>` element to e.g. add a `lang` attribute. You can achieve this the following way:

```js:title=gatsby-ssr.js
exports.onRenderBody = ({ setHtmlAttributes }) => {
setHtmlAttributes({ lang: "en" })
}
```

## Additional Resources

- [Adding an SEO component](/docs/how-to/adding-common-features/adding-seo-component)
Expand Down
5 changes: 0 additions & 5 deletions examples/using-gatsby-head/gatsby-ssr.tsx
View file
Open in desktop

This file was deleted.

1 change: 1 addition & 0 deletions examples/using-gatsby-head/src/components/seo.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ export const SEO: React.FC<React.PropsWithChildren<SEOProps>> = ({ title, descri

return (
<>
<html lang="en-US" />
<title>{seo.title}</title>
<meta name="description" content={seo.description} />
<meta name="image" content={seo.image} />
Expand Down