Override the Default Next.js Document

Lazar Nikolov
InstructorLazar Nikolov

Share this video with your friends

Send Tweet
Published 3 months ago
Updated 2 months ago

The Document is like the top level HTML structure of your Next.js application. By default it looks like this:

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

As you can see it looks pretty close to an HTML document but with custom components instead of the native tags. Here, you can introduce custom behavior like fonts, scripts, icons, etc.

Lazar Nikolov: [0:03] In the previous lesson, we learnt what the App component is, how to override it, and in which cases we want to override it.

[0:11] There's a similar concept in Next.js called the document. We can use a custom document to augment our applications HTML and body tags. For example, setting the language property of the HTML tag, add third-party scripts, link custom fonts, add analytics scripts, etc.

[0:32] To override the default document, we need to create the _document.tsx file into the Pages directory. Let's do that in exercise 8. Right-click on Pages, new file _document.tsx.

[0:49] Just like before, we need to export a default function called document, and we need to return something. Now in the case of the document, there are some things that we have to include in order everything to work properly.

[1:09] Let's import them from the next/document package. Those things would be the HTML components, the head component main, and next script. Let's go into the function and return this. First, it's the HTML component.

[1:30] This is basically the top-level HTML tag in every HTML document. Then is the head component. In this case, we don't have any children that's why it's self closing, but you have the ability to put additional stuff into the head component.

[1:44] Then our body, which is a simple HTML tag, we don't actually import the body as a component. Inside of the body, we have the main. That's where all of our pages render. We have the next script. This is the default configuration for the document.

[2:07] Let's run npm run dev and see what we get. There we go. We can see a document. We are overriding the document in Next.js. Nothing to see here. Nice. No errors, everything works perfectly. One thing that I need to mention, is that the document is only rendered in the server, so EventListeners like onClick will not work.

[2:34] As I mentioned earlier, we can override the document if you wanted to add the language property to the HTML, or add custom analytics scripts, or change the favicon. Let's try doing that.

[2:47] Before we make any changes, let's inspect our document. We can see that the HTML tag is here, the head tag contains some default elements from Next.js, here is our main component, and we have some additional Next.js scripts below.

[3:12] Let's go back and let's try to set the language property to English on the HTML itself, let's try to expand the head component. For the sake of simplicity, I will just paste a code snippet that will change the favicon to a cross on. Let's save this, and check out the changes.

[3:38] We can immediately see that the favicon is changed to a cross on, and we can see that the language is changed to English on the HTML tag. That's how you can override the document.

[3:53] Let's recap. Just like the App component, we can also override the document by creating the _document.tsx file into the Pages directory. We need to export a default function named document, and return the HTML head, main, and Next script in order for everything to work.

[4:12] Additionally, we can also add support for localization, change the favicon, we can also add our analytics scripts, or we can link custom CSS, custom fonts, etc.