Skip to content

Commit 0eea1be

Browse files
moleboxdelbaoliveira
molebox
and
delbaoliveira
authored
Docs: Refactor and tidy Link docs (vercel#69724)
This PR refactors the Link component docs page to follow a consistent structure according to our reference docs template. - Adds both typescript and javascript examples to all code blocks - Adds bot pages and app router examples to all code blocks where applicable - Re-structures the page Fixes: https://linear.app/vercel/issue/DOC-3258/nextlink <!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation - Run `pnpm prettier-fix` to fix formatting issues before opening the PR. - Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide ### Adding or Updating Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> --------- Co-authored-by: Delba de Oliveira <[email protected]> Co-authored-by: Delba de Oliveira <[email protected]>
1 parent d077768 commit 0eea1be

File tree

3 files changed

+858
-252
lines changed

3 files changed

+858
-252
lines changed

‎docs/02-app/01-building-your-application/01-routing/04-linking-and-navigating.mdx

Lines changed: 0 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -40,121 +40,6 @@ export default function Page() {
4040

4141
There are other optional props you can pass to `<Link>`. See the [API reference](/docs/app/api-reference/components/link) for more.
4242

43-
### Examples
44-
45-
#### Linking to Dynamic Segments
46-
47-
When linking to [dynamic segments](/docs/app/building-your-application/routing/dynamic-routes), you can use [template literals and interpolation](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Template_literals) to generate a list of links. For example, to generate a list of blog posts:
48-
49-
```jsx filename="app/blog/PostList.js"
50-
import Link from 'next/link'
51-
52-
export default function PostList({ posts }) {
53-
return (
54-
<ul>
55-
{posts.map((post) => (
56-
<li key={post.id}>
57-
<Link href={`/blog/${post.slug}`}>{post.title}</Link>
58-
</li>
59-
))}
60-
</ul>
61-
)
62-
}
63-
```
64-
65-
#### Checking Active Links
66-
67-
You can use [`usePathname()`](/docs/app/api-reference/functions/use-pathname) to determine if a link is active. For example, to add a class to the active link, you can check if the current `pathname` matches the `href` of the link:
68-
69-
```tsx filename="@/app/ui/nav-links.tsx" switcher
70-
'use client'
71-
72-
import { usePathname } from 'next/navigation'
73-
import Link from 'next/link'
74-
75-
export function Links() {
76-
const pathname = usePathname()
77-
78-
return (
79-
<nav>
80-
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
81-
Home
82-
</Link>
83-
84-
<Link
85-
className={`link ${pathname === '/about' ? 'active' : ''}`}
86-
href="/about"
87-
>
88-
About
89-
</Link>
90-
</nav>
91-
)
92-
}
93-
```
94-
95-
```jsx filename="@/app/ui/nav-links.tsx" switcher
96-
'use client'
97-
98-
import { usePathname } from 'next/navigation'
99-
import Link from 'next/link'
100-
101-
export function Links() {
102-
const pathname = usePathname()
103-
104-
return (
105-
<nav>
106-
<Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
107-
Home
108-
</Link>
109-
110-
<Link
111-
className={`link ${pathname === '/about' ? 'active' : ''}`}
112-
href="/about"
113-
>
114-
About
115-
</Link>
116-
</nav>
117-
)
118-
}
119-
```
120-
121-
#### Scrolling to an `id`
122-
123-
The default behavior of the Next.js App Router is to **scroll to the top of a new route or to maintain the scroll position for backwards and forwards navigation.**
124-
125-
If you'd like to scroll to a specific `id` on navigation, you can append your URL with a `#` hash link or just pass a hash link to the `href` prop. This is possible since `<Link>` renders to an `<a>` element.
126-
127-
```jsx
128-
<Link href="/dashboard#settings">Settings</Link>
129-
130-
// Output
131-
<a href="/dashboard#settings">Settings</a>
132-
```
133-
134-
> **Good to know**:
135-
>
136-
> - Next.js will scroll to the [Page](/docs/app/building-your-application/routing/pages) if it is not visible in the viewport upon navigation.
137-
138-
#### Disabling scroll restoration
139-
140-
The default behavior of the Next.js App Router is to **scroll to the top of a new route or to maintain the scroll position for backwards and forwards navigation.** If you'd like to disable this behavior, you can pass `scroll={false}` to the `<Link>` component, or `scroll: false` to `router.push()` or `router.replace()`.
141-
142-
```jsx
143-
// next/link
144-
<Link href="/dashboard" scroll={false}>
145-
Dashboard
146-
</Link>
147-
```
148-
149-
```jsx
150-
// useRouter
151-
import { useRouter } from 'next/navigation'
152-
153-
const router = useRouter()
154-
155-
router.push('/dashboard', { scroll: false })
156-
```
157-
15843
## `useRouter()` hook
15944

16045
The `useRouter` hook allows you to programmatically change routes from [Client Components](/docs/app/building-your-application/rendering/client-components).

0 commit comments

Comments
 (0)