Custom Document

A custom Document can update the <html> and <body> tags used to render a Page. This file is only rendered on the server, so event handlers like onClick cannot be used in _document.

To override the default Document, create the file pages/_document.js as shown below:

  1. import { Html, Head, Main, NextScript } from 'next/document'
  3. export default function Document() {
  4.   return (
  5.     <Html>
  6.       <Head />
  7.       <body>
  8.         <Main />
  9.         <NextScript />
  10.       </body>
  11.     </Html>
  12.   )
  13. }

The code above is the default Document added by Next.js. Custom attributes are allowed as props. For example, we might want to add lang="en" to the <html> tag:

  1. <Html lang="en">

Or add a className to the body tag:

  1. <body className="bg-white">

<Html>, <Head />, <Main /> and <NextScript /> are required for the page to be properly rendered.

Caveats

  • The <Head /> component used in _document is not the same as next/head. The <Head /> component used here should only be used for any <head> code that is common for all pages. For all other cases, such as <title> tags, we recommend using next/head in your pages or components.
  • React components outside of <Main /> will not be initialized by the browser. Do not add application logic here or custom CSS (like styled-jsx). If you need shared components in all your pages (like a menu or a toolbar), read Layouts instead.
  • Document currently does not support Next.js Data Fetching methods like getStaticProps or getServerSideProps.

Customizing renderPage

Note: This is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in styled-jsx support.

To prepare for React 18, we recommend avoiding customizing getInitialProps and renderPage, if possible.

The ctx object shown below is equivalent to the one received in getInitialProps, with the addition of renderPage.

  1. import Document, { Html, Head, Main, NextScript } from 'next/document'
  3. class MyDocument extends Document {
  4.   static async getInitialProps(ctx) {
  5.     const originalRenderPage = ctx.renderPage
  7.     // Run the React rendering logic synchronously
  8.     ctx.renderPage = () =>
  9.       originalRenderPage({
  10.         // Useful for wrapping the whole react tree
  11.         enhanceApp: (App) => App,
  12.         // Useful for wrapping in a per-page basis
  13.         enhanceComponent: (Component) => Component,
  14.       })
  16.     // Run the parent `getInitialProps`, it now includes the custom `renderPage`
  17.     const initialProps = await Document.getInitialProps(ctx)
  19.     return initialProps
  20.   }
  22.   render() {
  23.     return (
  24.       <Html>
  25.         <Head />
  26.         <body>
  27.           <Main />
  28.           <NextScript />
  29.         </body>
  30.       </Html>
  31.     )
  32.   }
  33. }
  35. export default MyDocument

Note: getInitialProps in _document is not called during client-side transitions.

TypeScript

You can use the built-in DocumentContext type and change the file name to ./pages/_document.tsx like so:

  1. import Document, { DocumentContext, DocumentInitialProps } from 'next/document'
  3. class MyDocument extends Document {
  4.   static async getInitialProps(
  5.     ctx: DocumentContext
  6.   ): Promise<DocumentInitialProps> {
  7.     const initialProps = await Document.getInitialProps(ctx)
  9.     return initialProps
  10.   }
  11. }
  13. export default MyDocument