Principle:Langgenius Dify NavigationPatterns
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, Navigation |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
Dify provides consistent navigation helpers that preserve URL query parameters across route transitions, preventing state loss when users move between related pages.
Description
The utils/navigation.ts module defines utility functions for constructing navigation paths that carry forward the current URL's query parameters. The primary function, createNavigationPath, accepts a base path and an optional preserveParams flag. When preservation is enabled (the default), it reads the current window.location.search parameters and appends them to the target path. This is particularly important in paginated list views where users drill into a detail page and then navigate back; without parameter preservation, the list resets to page 1, losing the user's scroll position, filter selections, and keyword searches.
The createBackNavigation function wraps createNavigationPath with a Next.js router instance, returning a callable function suitable for back button handlers and breadcrumb links. This factory pattern allows components to create the navigation handler once during render and pass it to onClick handlers or child components without recalculating the path on each invocation.
Both functions include defensive error handling: if window.location is unavailable (e.g., during server-side rendering) or the URL parsing fails, the functions fall back to the base path without query parameters. A console warning is emitted for debugging purposes. This resilience ensures that navigation never breaks, even in edge cases where the browser's location API is restricted or the URL format is unexpected.
Usage
Use this principle when:
- Implementing back navigation from detail pages to list views that support pagination or filtering
- Creating breadcrumb navigation that should preserve the user's position in paginated data
- Adding new route transitions between related pages where query parameter state matters
Theoretical Basis
This pattern implements State Preservation across navigation transitions, a core concept in User Interface State Management. The approach follows the Memento Pattern in a lightweight form, where the URL query string serves as the externalized state snapshot that can be restored when returning to a previous view. The factory function pattern (createBackNavigation) applies Partial Application from functional programming, pre-binding the router and base path to produce a zero-argument navigation action.