Unverified Commit b7eb7d35 authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

Docs: Clarify template.js behavior (#64781)

parent f7fef237
...@@ -198,12 +198,12 @@ The two layouts would be nested as such: ...@@ -198,12 +198,12 @@ The two layouts would be nested as such:
## Templates ## Templates
Templates are similar to layouts in that they wrap each child layout or page. Unlike layouts that persist across routes and maintain state, templates create a new instance for each of their children on navigation. This means that when a user navigates between routes that share a template, a new instance of the component is mounted, DOM elements are recreated, state is **not** preserved, and effects are re-synchronized. Templates are similar to layouts in that they wrap a child layout or page. Unlike layouts that persist across routes and maintain state, templates create a new instance for each of their children on navigation. This means that when a user navigates between routes that share a template, a new instance of the child is mounted, DOM elements are recreated, state is **not** preserved in Client Components, and effects are re-synchronized.
There may be cases where you need those specific behaviors, and templates would be a more suitable option than layouts. For example: There may be cases where you need those specific behaviors, and templates would be a more suitable option than layouts. For example:
- Features that rely on `useEffect` (e.g logging page views) and `useState` (e.g a per-page feedback form). - To resynchronize `useEffect` on navigation.
- To change the default framework behavior. For example, Suspense Boundaries inside layouts only show the fallback the first time the Layout is loaded and not when switching pages. For templates, the fallback is shown on each navigation. - To reset the state of a child Client Components on navigation.
A template can be defined by exporting a default React component from a `template.js` file. The component should accept a `children` prop. A template can be defined by exporting a default React component from a `template.js` file. The component should accept a `children` prop.
......
...@@ -3,7 +3,7 @@ title: template.js ...@@ -3,7 +3,7 @@ title: template.js
description: API Reference for the template.js file. description: API Reference for the template.js file.
--- ---
A **template** file is similar to a [layout](/docs/app/building-your-application/routing/pages-and-layouts#layouts) in that it wraps each child layout or page. Unlike layouts that persist across routes and maintain state, templates create a new instance for each of their children on navigation. A **template** file is similar to a [layout](/docs/app/building-your-application/routing/pages-and-layouts#layouts) 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.
```tsx filename="app/template.tsx" switcher ```tsx filename="app/template.tsx" switcher
export default function Template({ children }: { children: React.ReactNode }) { export default function Template({ children }: { children: React.ReactNode }) {
...@@ -25,7 +25,7 @@ export default function Template({ children }) { ...@@ -25,7 +25,7 @@ export default function Template({ children }) {
height="444" height="444"
/> />
While less common, you might choose a template over a layout if you want: While less common, you might choose to use a template over a layout if you want:
- Features that rely on `useEffect` (e.g logging page views) and `useState` (e.g a per-page feedback form). - Features that rely on `useEffect` (e.g logging page views) and `useState` (e.g a per-page feedback form).
- To change the default framework behavior. For example, Suspense Boundaries inside layouts only show the fallback the first time the Layout is loaded and not when switching pages. For templates, the fallback is shown on each navigation. - To change the default framework behavior. For example, Suspense Boundaries inside layouts only show the fallback the first time the Layout is loaded and not when switching pages. For templates, the fallback is shown on each navigation.
...@@ -34,11 +34,11 @@ While less common, you might choose a template over a layout if you want: ...@@ -34,11 +34,11 @@ While less common, you might choose a template over a layout if you want:
### `children` (required) ### `children` (required)
Template components should accept and use a `children` prop. `template` is rendered between a [layout](/docs/app/api-reference/file-conventions/layout) and its children. For example: Template accepts a `children` prop. For example:
```jsx filename="Output" ```jsx filename="Output"
<Layout> <Layout>
{/* Note that the template is given a unique key. */} {/* Note that the template is automatically given a unique key. */}
<Template key={routeParam}>{children}</Template> <Template key={routeParam}>{children}</Template>
</Layout> </Layout>
``` ```
...@@ -46,7 +46,7 @@ Template components should accept and use a `children` prop. `template` is rende ...@@ -46,7 +46,7 @@ Template components should accept and use a `children` prop. `template` is rende
> **Good to know**: > **Good to know**:
> >
> - By default, `template` is a [Server Component](/docs/app/building-your-application/rendering/server-components), but can also be used as a [Client Component](/docs/app/building-your-application/rendering/client-components) through the `"use client"` directive. > - By default, `template` is a [Server Component](/docs/app/building-your-application/rendering/server-components), but can also be used as a [Client Component](/docs/app/building-your-application/rendering/client-components) through the `"use client"` directive.
> - When a user navigates between routes that share a `template`, a new instance of the component is mounted, DOM elements are recreated, state is **not** preserved, and effects are re-synchronized. > - When a user navigates between routes that share a `template`, a new instance of the component is mounted, DOM elements are recreated, state is **not** preserved in Client Components, and effects are re-synchronized.
## Version History ## Version History
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment