Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Document prefetch null for App Router #61203

Merged
merged 7 commits into from
Jan 31, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 51 additions & 2 deletions docs/02-app/02-api-reference/01-components/link.mdx
Original file line number Diff line number Diff line change
@@ -77,13 +77,28 @@ export default Home

Here's a summary of the props available for the Link Component:

<PagesOnly>

| Prop | Example | Type | Required |
| ------------------------ | ------------------- | ---------------- | -------- |
| [`href`](#href-required) | `href="/dashboard"` | String or Object | Yes |
| [`replace`](#replace) | `replace={false}` | Boolean | - |
| [`scroll`](#scroll) | `scroll={false}` | Boolean | - |
| [`prefetch`](#prefetch) | `prefetch={false}` | Boolean | - |

</PagesOnly>

<AppOnly>

| Prop | Example | Type | Required |
| ------------------------ | ------------------- | ---------------- | -------- |
| [`href`](#href-required) | `href="/dashboard"` | String or Object | Yes |
| [`replace`](#replace) | `replace={false}` | Boolean | - |
| [`scroll`](#scroll) | `scroll={false}` | Boolean | - |
| [`prefetch`](#prefetch) | `prefetch={false}` | Boolean or null | - |

</AppOnly>

> **Good to know**: `<a>` tag attributes such as `className` or `target="_blank"` can be added to `<Link>` as props and will be passed to the underlying `<a>` element.

### `href` (required)
@@ -166,9 +181,13 @@ export default function Page() {

### `prefetch`

**Defaults to `true`.** When `true`, `next/link` will prefetch the page (denoted by the `href`) in the background. This is useful for improving the performance of client-side navigations. Any `<Link />` in the viewport (initially or through scroll) will be preloaded.
<AppOnly>

Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production.
Prefetching happens when a `<Link />` component enters the user's viewport (initially or through scroll). Next.js prefetches and loads the linked route (denoted by the `href`) in the background to improve the performance of client-side navigations. Prefetching is only enabled in production.

- `null` (default): Prefetch behavior depends on whether the route is static or dynamic. For static routes, the full route will be prefetched. For dynamic routes, the partial route down to the nearest segment with a [`loading.js`](/docs/app/building-your-application/routing/loading-ui-and-streaming#instant-loading-states) boundary will be prefetched.
delbaoliveira marked this conversation as resolved.
Show resolved Hide resolved
- `true`: The full route will be prefetched for both static and dynamic routes.
delbaoliveira marked this conversation as resolved.
Show resolved Hide resolved
- `false`: Prefetching will be disabled.

```tsx filename="app/page.tsx" switcher
import Link from 'next/link'
@@ -194,8 +213,38 @@ export default function Page() {
}
```

</AppOnly>

<PagesOnly>

**Defaults to `true`.** When `true`, `next/link` will prefetch the page (denoted by the `href`) in the background. This improves the performance of client-side navigations. Any `<Link />` in the viewport (initially or through scroll) will be prefetched and loaded in the background.

Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production.
delbaoliveira marked this conversation as resolved.
Show resolved Hide resolved

```tsx filename="pages/index.tsx" switcher
import Link from 'next/link'

export default function Page() {
return (
<Link href="/dashboard" prefetch={false}>
Dashboard
</Link>
)
}
```

```jsx filename="pages/index.js" switcher
import Link from 'next/link'

export default function Page() {
return (
<Link href="/dashboard" prefetch={false}>
Dashboard
</Link>
)
}
```

## Other Props

### `legacyBehavior`