Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

useNavigate.tsx

80 lines2.3 KB

1'use client'
2​
3import * as React from 'react'
4import { useLayoutEffect } from './utils'
5import { useRouter } from './useRouter'
6import type {
7 AnyRouter,
8 FromPathOption,
9 NavigateOptions,
10 RegisteredRouter,
11 UseNavigateResult,
12} from '@tanstack/router-core'
13​
14/**
15 * Imperative navigation hook.
16 *
17 * Returns a stable `navigate(options)` function to change the current location
18 * programmatically. Prefer the `Link` component for user-initiated navigation,
19 * and use this hook from effects, callbacks, or handlers where imperative
20 * navigation is required.
21 *
22 * Options:
23 * - `from`: Optional route base used to resolve relative `to` paths.
24 *
25 * @returns A function that accepts `NavigateOptions`.
26 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useNavigateHook
27 */
28export function useNavigate<
29 TRouter extends AnyRouter = RegisteredRouter,
30 TDefaultFrom extends string = string,
31>(_defaultOpts?: {
32 from?: FromPathOption<TRouter, TDefaultFrom>
33}): UseNavigateResult<TDefaultFrom> {
34 const router = useRouter()
35​
36 return React.useCallback(
37 (options: NavigateOptions) => {
38 return router.navigate({
39 ...options,
40 from: options.from ?? _defaultOpts?.from,
41 })
42 },
43 [_defaultOpts?.from, router],
44 ) as UseNavigateResult<TDefaultFrom>
46​
47/**
48 * Component that triggers a navigation when rendered. Navigation executes
49 * in an effect after mount/update.
50 *
51 * Props are the same as `NavigateOptions` used by `navigate()`.
52 *
53 * @returns null
54 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/navigateComponent
55 */
56export function Navigate<
57 TRouter extends AnyRouter = RegisteredRouter,
58 const TFrom extends string = string,
59 const TTo extends string | undefined = undefined,
60 const TMaskFrom extends string = TFrom,
61 const TMaskTo extends string = '',
62>(props: NavigateOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>): null {
63 const router = useRouter()
64 const navigate = useNavigate()
65​
66 const previousPropsRef = React.useRef<NavigateOptions<
67 TRouter,
68 TFrom,
69 TTo,
70 TMaskFrom,
71 TMaskTo
72 > | null>(null)
73 useLayoutEffect(() => {
74 if (previousPropsRef.current !== props) {
75 navigate(props)
76 previousPropsRef.current = props
77 }
78 }, [router, props, navigate])
79 return null