template.js

A template file is similar to a layout in that it wraps a layout or page. Unlike layouts that persist across routes and maintain state, templates are given a unique key, meaning children Client Components reset their state on navigation.

They are useful when you need to:

• Resynchronize useEffect on navigation.
• Reset the state of a child Client Components on navigation. For example, an input field.
• To change default framework behavior. For example, Suspense boundaries inside layouts only show a fallback on first load, while templates show it on every navigation.

Convention

A template can be defined by exporting a default React component from a template.js file. The component should accept a children prop.

<Image alt="template.js special file" srcLight="/docs/light/template-special-file.png" srcDark="/docs/dark/template-special-file.png" width="1600" height="444" />

export default function Template({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}

export default function Template({ children }) {
  return <div>{children}</div>
}

In terms of nesting, template.js is rendered between a layout and its children. Here's a simplified output:

<Layout>
  <Template key={routeParam}>{children}</Template>
</Layout>

Props

children (required)

Template accepts a children prop.

<Layout>
  <Template key={routeParam}>{children}</Template>
</Layout>

Behavior

• Server Components: By default, templates are Server Components.
• Remount on navigation: Templates receive a unique key automatically. Navigating to a new route causes the template and its children to remount.
• State reset: Any Client Component inside the template will reset its state on navigation.
• Effect re-run: Effects like useEffect will re-synchronize as the component remounts.
• DOM reset: DOM elements inside the template are fully recreated.

Version History