Clarifying valid ways to manage HTML head in App Router #80725

drbalm · 2025-06-20T16:22:32Z

drbalm
Jun 20, 2025

From reading Next.js App Router docs, I have the impression that we need to use Metadata APIs and perhaps the Script component (e.g., beforeInteractive) for updating what ends up in the HTML head element.

On the other hand, I also see some examples that show head in the Root Layout src/app/layout.tsx.

Is manually coding the head element in src/app/layout.tsx valid / supported by Next.js? Or are these examples out of date?

If it's valid, is there any guarantee on the order elements get added to the head in relation to what was manually coded?

Clarifications / answers here may also help answer #75469.

Thanks for any insights.

SMatvii · 2025-06-22T18:19:55Z

SMatvii
Jun 22, 2025

1. Is manually coding the `<head>` element in `src/app/layout.tsx` valid/supported?

Yes, it is supported.

In the Next.js App Router (app/ directory), you can include a <head> element directly in your layout.tsx (or layout.jsx) files.
This is documented as valid, and is used to add static elements to the document head.

Example from official docs:

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        {/* Custom elements */}
        <link rel="preconnect" href="https://fonts.googleapis.com" />
      </head>
      <body>{children}</body>
    </html>
  );
}

See the official docs:
Next.js Layouts | Customizing Head

The examples you linked are not out of date for this usage—they’re correct.

2. Should you use the `<head>` element, Metadata API, or `<Script>`?

Static head elements (that don’t change per-page):
Use the <head> element in layout.tsx.
Dynamic metadata (title, description, social tags, etc.):
Use the Metadata API.
This lets Next.js manage deduplication, ordering, and SSR/SEO optimizations.
Loading scripts:
Use the <Script> component for controlling when/how scripts load (e.g., beforeInteractive).

3. Is there any guarantee about the order of head elements?

Order is generally preserved:
Elements you place directly in <head> in your layout.tsx will render in the order you specify, before other head elements generated by the Metadata API or by child routes/layouts.
However:
- Next.js collects and merges head elements from all layouts and pages, and may deduplicate or reorder some tags (e.g., multiple <title> or <meta name="description">).
- The official docs state:
  
  "Head elements will be placed in the order they are encountered in your layout hierarchy, with parent layouts first."
- For critical ordering requirements (like placing scripts before/after certain tags), use <Script> with its loading strategy.

References:

3 replies

drbalm Jun 23, 2025
Author

I'm not seeing the "Customizing Head" section when I navigate to Next.js Docs: Customizing Head. Is that a valid section on this page?

I haven't found any examples of <head> being used in the docs on my read through, so that's why I'm still unsure.

icyJoseph Jun 23, 2025
Collaborator

Hi,

At the end of the day these are React APIs.

https://react.dev/reference/react-dom/components/link

React will always place the DOM element corresponding to the <link> component within the document’s , regardless of where in the React tree it is rendered. The <head> is the only valid place for <link> to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render <link> components itself.

There are a few exceptions to this:

If the <link> has a rel="stylesheet" prop, then it has to also have a precedence prop to get this special behavior. This is because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the precedence prop. If the precedence prop is omitted, there is no special behavior.
If the <link> has an itemProp prop, there is no special behavior, because in this case it doesn’t apply to the document but instead represents metadata about a specific part of the page.
If the <link> has an onLoad or onError prop, because in that case you are managing the loading of the linked resource manually within your React component.

For scripts, yeah, use beforeInteractive.

Read through the React docs for each tag you are curious about.

Next.js has some APIs around Metadata to make it more manageable, but you can opt out if you want, though not recommended.

1chooo Jun 23, 2025

I could not find the "Customizing Head" section in Next.js Docs: Customizing Head.

However, I found out there is the description related to <head> in Next.js Docs: layout.js#metadata

Good to know: You should not manually add <head> tags such as <title> and <meta> to root layouts. Instead, use the Metadata APIs which automatically handles advanced requirements such as streaming and de-duplicating <head> elements.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Clarifying valid ways to manage HTML head in App Router #80725

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment 3 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Clarifying valid ways to manage HTML head in App Router #80725

Uh oh!

drbalm Jun 20, 2025

Replies: 1 comment · 3 replies

Uh oh!

SMatvii Jun 22, 2025

1. Is manually coding the <head> element in src/app/layout.tsx valid/supported?

2. Should you use the <head> element, Metadata API, or <Script>?

3. Is there any guarantee about the order of head elements?

Uh oh!

Uh oh!

drbalm Jun 23, 2025 Author

Uh oh!

icyJoseph Jun 23, 2025 Collaborator

Uh oh!

1chooo Jun 23, 2025

drbalm
Jun 20, 2025

Replies: 1 comment 3 replies

SMatvii
Jun 22, 2025

1. Is manually coding the `<head>` element in `src/app/layout.tsx` valid/supported?

2. Should you use the `<head>` element, Metadata API, or `<Script>`?

drbalm Jun 23, 2025
Author

icyJoseph Jun 23, 2025
Collaborator