Unverified Commit 828211ef authored by Joseph's avatar Joseph Committed by GitHub

docs: Templates on navigation (#84493)

The docs on Template and its life cycle, were not that clear.

Closes:
https://linear.app/vercel/issue/DOC-5107/review-templates-api-reference

---------
Co-authored-by: 's avatarIsmael <ismael@vercel.com>
parent 45fcbdea
...@@ -60,11 +60,99 @@ Template accepts a `children` prop. ...@@ -60,11 +60,99 @@ Template accepts a `children` prop.
## Behavior ## Behavior
- **Server Components**: By default, templates are Server Components. - **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. - **With navigation**: Templates receive a unique key for their own segment level. They remount when that segment (including its dynamic params) changes. Navigations within deeper segments do not remount higher-level templates. Search params do not trigger remounts.
- **State reset**: Any Client Component inside the template will reset its state on navigation. - **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. - **Effect re-run**: Effects like `useEffect` will re-synchronize as the component remounts.
- **DOM reset**: DOM elements inside the template are fully recreated. - **DOM reset**: DOM elements inside the template are fully recreated.
### Templates during navigation and remounting
This section illustrates how templates behave during navigation. It shows, step by step, which templates remount on each route change and why.
Using this project tree:
```
app
├── about
│   ├── page.tsx
├── blog
│   ├── [slug]
│   │   └── page.tsx
│   ├── page.tsx
│   └── template.tsx
├── layout.tsx
├── page.tsx
└── template.tsx
```
Starting at `/`, the React tree looks roughly like this.
> Note: The `key` values shown in the examples are illustrative, the values in your application may differ.
```jsx filename="Output"
<RootLayout>
{/* app/template.tsx */}
<Template key="/">
<Page />
</Template>
</RootLayout>
```
Navigating to `/about` (first segment changes), the root template key changes, it remounts:
```jsx filename="Output"
<RootLayout>
{/* app/template.tsx */}
<Template key="/about">
<AboutPage />
</Template>
</RootLayout>
```
Navigating to `/blog` (first segment changes), the root template key changes, it remounts and the blog-level template mounts:
```jsx filename="Output"
<RootLayout>
{/* app/template.tsx (root) */}
<Template key="/blog">
{/* app/blog/template.tsx */}
<Template key="/blog">
<BlogIndexPage />
</Template>
</Template>
</RootLayout>
```
Navigating within the same first segment to `/blog/first-post` (child segment changes), the root template key doesn't change, but the blog-level template key changes, it remounts:
```jsx filename="Output"
<RootLayout>
{/* app/template.tsx (root) */}
<Template key="/blog">
{/* app/blog/template.tsx */}
{/* remounts because the child segment at this level changed */}
<Template key="/blog/first-post">
<BlogPostPage slug="first-post" />
</Template>
</Template>
</RootLayout>
```
Navigating to `/blog/second-post` (same first segment, different child segment), the root template key doesn't change, but the blog-level template key changes, it remounts again:
```jsx filename="Output"
<RootLayout>
{/* app/template.tsx (root) */}
<Template key="/blog">
{/* app/blog/template.tsx */}
{/* remounts again due to changed child segment */}
<Template key="/blog/second-post">
<BlogPostPage slug="second-post" />
</Template>
</Template>
</RootLayout>
```
## Version History ## Version History
| Version | Changes | | Version | Changes |
......
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