Overview
Provides helper functions for consistent navigation behavior with query parameter preservation throughout the Dify frontend application.
Description
This module addresses a common frontend navigation pattern: preserving URL query parameters (such as pagination state, search keywords, and filters) when users navigate between related pages. createNavigationPath builds a full URL path by appending the current window's query string to a base path. createBackNavigation returns a closure that performs a router push with preserved parameters, suitable for back-button handlers. extractQueryParams selectively extracts named parameters from the current URL. createNavigationPathWithParams builds a path from an explicit parameter object. mergeQueryParams combines current URL parameters with new overrides, supporting deletion via null values. The module also exports a datasetNavigation namespace object with pre-built navigation helpers for common dataset and document page transitions.
Usage
Use these utilities in any component that needs to navigate while maintaining list state (pagination, search, filters). The datasetNavigation helpers are specifically designed for dataset document list and detail views.
Code Reference
Source Location
Signature
export function createNavigationPath(
basePath: string,
preserveParams: boolean = true,
): string
export function createBackNavigation(
router: { push: (path: string) => void },
basePath: string,
preserveParams: boolean = true,
): () => void
export function extractQueryParams(
paramNames: string[],
): Record<string, string>
export function createNavigationPathWithParams(
basePath: string,
params: Record<string, string | number>,
): string
export function mergeQueryParams(
newParams: Record<string, string | number | null | undefined>,
preserveExisting: boolean = true,
): URLSearchParams
export const datasetNavigation: {
backToDocuments: (router: { push: (path: string) => void }, datasetId: string) => () => void
toDocumentDetail: (router: { push: (path: string) => void }, datasetId: string, documentId: string) => () => void
toDocumentSettings: (router: { push: (path: string) => void }, datasetId: string, documentId: string) => () => void
}
Import
import {
createNavigationPath,
createBackNavigation,
extractQueryParams,
createNavigationPathWithParams,
mergeQueryParams,
datasetNavigation,
} from '@/utils/navigation'
I/O Contract
Inputs (createNavigationPath)
| Name |
Type |
Required |
Description
|
| basePath |
string |
Yes |
The base path to navigate to (e.g., "/datasets/123/documents")
|
| preserveParams |
boolean |
No (default: true) |
Whether to append the current URL's query parameters
|
Inputs (createBackNavigation)
| Name |
Type |
Required |
Description
|
| router |
{ push: (path: string) => void } |
Yes |
A Next.js router instance or compatible object
|
| basePath |
string |
Yes |
The base path to navigate back to
|
| preserveParams |
boolean |
No (default: true) |
Whether to preserve current query parameters
|
| Name |
Type |
Required |
Description
|
| paramNames |
string[] |
Yes |
Array of parameter names to extract from the current URL
|
Inputs (createNavigationPathWithParams)
| Name |
Type |
Required |
Description
|
| basePath |
string |
Yes |
The base path
|
| params |
number> |
Yes |
Query parameters to include in the path
|
Inputs (mergeQueryParams)
| Name |
Type |
Required |
Description
|
| newParams |
number | null | undefined> |
Yes |
New parameters to add or override; null/undefined values cause deletion
|
| preserveExisting |
boolean |
No (default: true) |
Whether to start from the current URL parameters
|
Outputs
| Function |
Type |
Description
|
| createNavigationPath |
string |
Full path with optional query string appended
|
| createBackNavigation |
() => void |
A callback that performs router.push with the constructed path
|
| extractQueryParams |
Record<string, string> |
Object of extracted parameter name-value pairs
|
| createNavigationPathWithParams |
string |
Path with explicitly provided query parameters
|
| mergeQueryParams |
URLSearchParams |
Merged parameters as a URLSearchParams instance
|
Usage Examples
import { createBackNavigation } from '@/utils/navigation'
import { useRouter } from 'next/navigation'
const router = useRouter()
// Current URL: /datasets/abc/documents/456?page=3&limit=10&keyword=test
const backToPrev = createBackNavigation(router, '/datasets/abc/documents')
// Navigates to: /datasets/abc/documents?page=3&limit=10&keyword=test
backToPrev()
Use Dataset Navigation Helpers
import { datasetNavigation } from '@/utils/navigation'
import { useRouter } from 'next/navigation'
const router = useRouter()
const goBack = datasetNavigation.backToDocuments(router, 'dataset-123')
const goToDetail = datasetNavigation.toDocumentDetail(router, 'dataset-123', 'doc-456')
// In JSX:
// <button onClick={goBack}>Back to Documents</button>
// <button onClick={goToDetail}>View Document</button>
Merge Query Parameters
import { mergeQueryParams } from '@/utils/navigation'
// Current URL: /page?page=3&limit=10
const merged = mergeQueryParams({ keyword: 'test', page: '1' })
// Result: page=1&limit=10&keyword=test (page overridden, limit preserved, keyword added)
Related Pages
