▲Next.js

Custom Document Component

Updated 2026-04-20

3 min read

Custom Document Component

In this section, we will explore how to create a custom Document component in Next.js. The Document component is a special component that allows you to customize the initial HTML document rendered by Next.js. This can be particularly useful for adding global styles, scripts, or meta tags.

Introduction to the Document Component

By default, Next.js provides a basic Document component that includes essential elements like <html>, <head>, and <body>. However, in many cases, you might need to customize these elements to fit your application's requirements. For instance, you might want to add custom meta tags for SEO, include global stylesheets, or load specific scripts.

Creating a Custom Document Component

To create a custom Document component, follow these steps:

Create the _document.js File: This file should be placed in the pages directory at the root of your Next.js project.
Extend the Default Document Class: Use the Document class provided by Next.js and extend it to customize its behavior.

Here's a basic example of how to create a custom Document component:

// pages/_document.js

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

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {/* Add your custom meta tags here */}
          <meta name="description" content="Custom Document Component Example" />
          <link rel="icon" href="/favicon.ico" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Explanation

<Html>: Represents the <html> tag. You can add attributes like lang.
<Head>: Represents the <head> tag. This is where you can add meta tags, links to stylesheets, and other head elements.
<Main>: A built-in component that renders the main content of your application.
<NextScript>: A built-in component that includes all the necessary scripts for your Next.js app.

Adding Global Styles

To include global styles in your custom Document component, you can import them directly into the _document.js file. Here's an example:

// pages/_document.js

import { Html, Head, Main, NextScript } from 'next/document';
import '../styles/global.css'; // Import your global stylesheet

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {/* Add your custom meta tags here */}
          <meta name="description" content="Custom Document Component Example" />
          <link rel="icon" href="/favicon.ico" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Explanation

import '../styles/global.css';: This line imports your global stylesheet. Make sure the path is correct relative to the _document.js file.

Adding Custom Scripts

If you need to include custom scripts, such as Google Analytics or other tracking scripts, you can add them within the <Head> or <body> tags of your Document component. Here's an example:

// pages/_document.js

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

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {/* Add your custom meta tags here */}
          <meta name="description" content="Custom Document Component Example" />
          <link rel="icon" href="/favicon.ico" />
          {/* Include Google Analytics script */}
          <script
            async
            src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
          ></script>
          <script
            dangerouslySetInnerHTML={{
              __html: `
                window.dataLayer = window.dataLayer || [];
                function gtag(){dataLayer.push(arguments);}
                gtag('js', new Date());
                gtag('config', 'GA_MEASUREMENT_ID');
              `,
            }}
          />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Explanation

<script> Tag: This tag is used to include the Google Analytics script. The dangerouslySetInnerHTML prop is used to inject raw HTML into the component, which is necessary for scripts.

Best Practices

Keep It Simple: Only customize what you need. Over-customizing can lead to maintenance issues.
Avoid Inline Styles: Use external stylesheets instead of inline styles within the Document component.
Use Environment Variables: For sensitive information like API keys or tracking IDs, use environment variables.
Test Thoroughly: After making changes to the Document component, test your application thoroughly to ensure everything works as expected.

Conclusion

The custom Document component in Next.js is a powerful tool for controlling the initial HTML document rendered by your application. By following the steps outlined in this tutorial, you can customize meta tags, include global stylesheets, and add scripts as needed. Remember to keep your implementation simple and maintainable, and always test thoroughly after making changes.

This guide should provide you with a solid foundation for creating a custom Document component in Next.js. Happy coding!

▲Next.js

Custom Document Component

Updated 2026-04-20

3 min read

Custom Document Component

Introduction to the Document Component

Creating a Custom Document Component

To create a custom Document component, follow these steps:

Create the _document.js File: This file should be placed in the pages directory at the root of your Next.js project.
Extend the Default Document Class: Use the Document class provided by Next.js and extend it to customize its behavior.

Here's a basic example of how to create a custom Document component:

// pages/_document.js

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

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {/* Add your custom meta tags here */}
          <meta name="description" content="Custom Document Component Example" />
          <link rel="icon" href="/favicon.ico" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Explanation

<Html>: Represents the <html> tag. You can add attributes like lang.
<Head>: Represents the <head> tag. This is where you can add meta tags, links to stylesheets, and other head elements.
<Main>: A built-in component that renders the main content of your application.
<NextScript>: A built-in component that includes all the necessary scripts for your Next.js app.

Adding Global Styles

To include global styles in your custom Document component, you can import them directly into the _document.js file. Here's an example:

// pages/_document.js

import { Html, Head, Main, NextScript } from 'next/document';
import '../styles/global.css'; // Import your global stylesheet

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {/* Add your custom meta tags here */}
          <meta name="description" content="Custom Document Component Example" />
          <link rel="icon" href="/favicon.ico" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Explanation

import '../styles/global.css';: This line imports your global stylesheet. Make sure the path is correct relative to the _document.js file.

Adding Custom Scripts

If you need to include custom scripts, such as Google Analytics or other tracking scripts, you can add them within the <Head> or <body> tags of your Document component. Here's an example:

// pages/_document.js

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

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {/* Add your custom meta tags here */}
          <meta name="description" content="Custom Document Component Example" />
          <link rel="icon" href="/favicon.ico" />
          {/* Include Google Analytics script */}
          <script
            async
            src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
          ></script>
          <script
            dangerouslySetInnerHTML={{
              __html: `
                window.dataLayer = window.dataLayer || [];
                function gtag(){dataLayer.push(arguments);}
                gtag('js', new Date());
                gtag('config', 'GA_MEASUREMENT_ID');
              `,
            }}
          />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Explanation

<script> Tag: This tag is used to include the Google Analytics script. The dangerouslySetInnerHTML prop is used to inject raw HTML into the component, which is necessary for scripts.

Best Practices

Keep It Simple: Only customize what you need. Over-customizing can lead to maintenance issues.
Avoid Inline Styles: Use external stylesheets instead of inline styles within the Document component.
Use Environment Variables: For sensitive information like API keys or tracking IDs, use environment variables.
Test Thoroughly: After making changes to the Document component, test your application thoroughly to ensure everything works as expected.

Conclusion

This guide should provide you with a solid foundation for creating a custom Document component in Next.js. Happy coding!