Skip to content

Commit 8b53a9a

Browse files
tannerlinsleycursoragent
tannerlinsley
and
cursoragent
authored
docs: basic search params how-to
Add 'Navigate with Search Parameters' how-to guide covering various navigation methods for search parameters. This guide details how to update and manage search parameters using both Link components and programmatic navigation (`useNavigate`, router instance). It covers basic and functional updates, navigation with route changes, advanced patterns like conditional navigation and validation, common UI patterns (search results, filters, breadcrumbs), and addresses common problems like losing parameters or serialization issues. --- [Open in Web](https://cursor.com/agents?id=bc-38c6eb35-f409-43fc-ac4c-323097fb478b) • [Open in Cursor](https://cursor.com/background-agent?bcId=bc-38c6eb35-f409-43fc-ac4c-323097fb478b) • [Open Docs](https://docs.cursor.com/background-agent/web-and-mobile) --------- Co-authored-by: Cursor Agent <[email protected]>
1 parent 4a1edf6 commit 8b53a9a

8 files changed

+971
-2
lines changed

‎docs/router/framework/react/how-to/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ This directory contains focused, step-by-step instructions for common TanStack R
3939
**Foundation Level (Start Here):**
4040

4141
- [x] [Set Up Basic Search Parameters](./setup-basic-search-params.md) - Create type-safe search validation and reading
42-
- [ ] Navigate with Search Parameters - Update and manage search params with Links and navigation
42+
- [x] [Navigate with Search Parameters](./navigate-with-search-params.md) - Update and manage search params with Links and navigation
4343

4444
**Intermediate Level (Common Patterns):**
4545

‎docs/router/framework/react/how-to/drafts/README.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# How-To Guide Drafts
2+
3+
This directory contains draft content for upcoming how-to guides in the Progressive Search Parameters Series. Each draft file contains:
4+
5+
- **Metadata** about the final destination and dependencies
6+
- **Staged content** extracted from other guides to avoid scope creep
7+
- **Implementation notes** for future development
8+
- **Cross-reference planning** for proper guide linking
9+
10+
## File Naming Convention
11+
12+
- `{guide-name}.draft.md` - Draft content for upcoming guides
13+
- Clear metadata header with destination path and status
14+
15+
## Current Drafts
16+
17+
### ⏳ Ready for Implementation (Substantial Content Available)
18+
19+
1. **`validate-search-params.draft.md`**
20+
- **Destination:** `validate-search-params.md`
21+
- **Position:** Intermediate Level - Guide #3
22+
- **Content:** Schema validation, type safety, error handling
23+
24+
2. **`build-search-filtering-systems.draft.md`**
25+
- **Destination:** `build-search-filtering-systems.md`
26+
- **Position:** Specialized Use Cases - Guide #9
27+
- **Content:** Complete filtering UIs, search results, pagination
28+
29+
3. **`search-params-in-forms.draft.md`**
30+
- **Destination:** `search-params-in-forms.md`
31+
- **Position:** Specialized Use Cases - Guide #10
32+
- **Content:** Form synchronization, state management
33+
34+
4. **`optimize-search-param-performance.draft.md`**
35+
- **Destination:** `optimize-search-param-performance.md`
36+
- **Position:** Advanced Level - Guide #7
37+
- **Content:** Performance optimization, memoization patterns
38+
39+
## Implementation Workflow
40+
41+
When implementing a guide from a draft:
42+
43+
1. **Copy the staged content** to the final destination
44+
2. **Expand with additional examples** specific to the guide's focus
45+
3. **Add comprehensive troubleshooting** for the domain
46+
4. **Update cross-references** in related guides
47+
5. **Update the main README** to mark guide as completed
48+
6. **Delete the draft file** once fully implemented
49+
50+
## Benefits of This System
51+
52+
- **Prevents scope creep** in individual guides
53+
- **Preserves valuable content** during refactoring
54+
- **Enables focused guide development**
55+
- **Maintains clear progression** through the series
56+
- **Facilitates parallel development** of multiple guides
57+
58+
## Content Sources
59+
60+
Most staged content originates from:
61+
- `navigate-with-search-params.md` - Content moved to maintain focus
62+
- Implementation planning sessions
63+
- User feedback and common questions

‎docs/router/framework/react/how-to/drafts/build-search-filtering-systems.draft.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# DRAFT: Build Search-Based Filtering Systems
2+
3+
**Final Destination:** `docs/router/framework/react/how-to/build-search-filtering-systems.md`
4+
**Progressive Series Position:** Specialized Use Cases - Guide #9
5+
**Depends On:** `setup-basic-search-params.md`, `navigate-with-search-params.md`, `validate-search-params.md`
6+
**Status:** Ready for implementation - comprehensive UI patterns available
7+
8+
---
9+
10+
## Content Staged from navigate-with-search-params.md
11+
12+
### Search Result Navigation
13+
14+
Handle search result navigation with query preservation:
15+
16+
```tsx
17+
import { Link, useSearch } from '@tanstack/react-router'
18+
19+
function SearchResults() {
20+
const search = useSearch({ from: '/search' })
21+
22+
return (
23+
<div>
24+
{/* Preserve search query, change view */}
25+
<nav>
26+
<Link search={(prev) => ({ ...prev, view: 'grid' })}>
27+
Grid View
28+
</Link>
29+
<Link search={(prev) => ({ ...prev, view: 'list' })}>
30+
List View
31+
</Link>
32+
</nav>
33+
34+
{/* Pagination with query preservation */}
35+
<div>
36+
{search.page > 1 && (
37+
<Link search={(prev) => ({ ...prev, page: prev.page - 1 })}>
38+
Previous
39+
</Link>
40+
)}
41+
42+
<Link search={(prev) => ({ ...prev, page: (prev.page || 1) + 1 })}>
43+
Next
44+
</Link>
45+
</div>
46+
47+
{/* Related searches */}
48+
<div>
49+
Related searches:
50+
{[
51+
'laptops gaming',
52+
'laptops business',
53+
'laptops student'
54+
].map(suggestion => (
55+
<Link
56+
key={suggestion}
57+
search={(prev) => ({ ...prev, query: suggestion, page: 1 })}
58+
>
59+
{suggestion}
60+
</Link>
61+
))}
62+
</div>
63+
</div>
64+
)
65+
}
66+
```
67+
68+
### Filter Navigation
69+
70+
Build filtering interfaces with search parameter navigation:
71+
72+
```tsx
73+
import { Link, useSearch } from '@tanstack/react-router'
74+
75+
const categories = ['electronics', 'clothing', 'books', 'home']
76+
const sortOptions = [
77+
{ value: 'relevance', label: 'Relevance' },
78+
{ value: 'price-asc', label: 'Price: Low to High' },
79+
{ value: 'price-desc', label: 'Price: High to Low' },
80+
{ value: 'rating', label: 'Customer Rating' }
81+
]
82+
83+
function FilterNavigation() {
84+
const search = useSearch({ from: '/products' })
85+
86+
return (
87+
<aside>
88+
{/* Category filters */}
89+
<div>
90+
<h3>Categories</h3>
91+
{categories.map(category => (
92+
<Link
93+
key={category}
94+
search={(prev) => ({
95+
...prev,
96+
category: prev.category === category ? undefined : category,
97+
page: 1
98+
})}
99+
className={search.category === category ? 'active' : ''}
100+
>
101+
{category}
102+
</Link>
103+
))}
104+
</div>
105+
106+
{/* Sort options */}
107+
<div>
108+
<h3>Sort By</h3>
109+
{sortOptions.map(option => (
110+
<Link
111+
key={option.value}
112+
search={(prev) => ({ ...prev, sort: option.value, page: 1 })}
113+
className={search.sort === option.value ? 'active' : ''}
114+
>
115+
{option.label}
116+
</Link>
117+
))}
118+
</div>
119+
120+
{/* Clear all filters */}
121+
<Link
122+
search={(prev) => {
123+
const { category, sort, minPrice, maxPrice, ...rest } = prev
124+
return rest
125+
}}
126+
>
127+
Clear All Filters
128+
</Link>
129+
</aside>
130+
)
131+
}
132+
```
133+
134+
### Programmatic Search Controls
135+
136+
Navigate programmatically with search parameter updates:
137+
138+
```tsx
139+
import { useNavigate } from '@tanstack/react-router'
140+
141+
function SearchControls() {
142+
const navigate = useNavigate()
143+
144+
const handleSortChange = (sortBy: string) => {
145+
navigate({
146+
search: (prev) => ({ ...prev, sort: sortBy, page: 1 })
147+
})
148+
}
149+
150+
const handleClearFilters = () => {
151+
navigate({
152+
search: (prev) => {
153+
const { category, minPrice, maxPrice, ...rest } = prev
154+
return rest
155+
}
156+
})
157+
}
158+
159+
return (
160+
<div>
161+
<select onChange={(e) => handleSortChange(e.target.value)}>
162+
<option value="relevance">Sort by Relevance</option>
163+
<option value="price-asc">Price: Low to High</option>
164+
<option value="price-desc">Price: High to Low</option>
165+
</select>
166+
167+
<button onClick={handleClearFilters}>
168+
Clear Filters
169+
</button>
170+
</div>
171+
)
172+
}
173+
```
174+
175+
---
176+
177+
## Implementation Notes
178+
179+
### Additional Content Needed:
180+
- [ ] Complete e-commerce filtering example
181+
- [ ] Advanced filter combinations (price ranges, multi-select)
182+
- [ ] Filter state persistence and sharing
183+
- [ ] Search result highlighting and sorting
184+
- [ ] Infinite scroll pagination patterns
185+
- [ ] Filter URL state management best practices
186+
- [ ] Accessibility considerations for filter UIs
187+
- [ ] Mobile-responsive filter patterns
188+
189+
### Cross-References to Add:
190+
- Link to `setup-basic-search-params.md` for foundation
191+
- Link to `navigate-with-search-params.md` for navigation patterns
192+
- Link to `validate-search-params.md` for filter validation
193+
- Forward link to `search-params-with-data-loading.md` for data integration
194+
195+
### README Update Required:
196+
- [ ] Mark guide as completed in progressive series
197+
- [ ] Uncomment "Common Next Steps" in related guides

‎docs/router/framework/react/how-to/drafts/optimize-search-param-performance.draft.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# DRAFT: Optimize Search Parameter Performance
2+
3+
**Final Destination:** `docs/router/framework/react/how-to/optimize-search-param-performance.md`
4+
**Progressive Series Position:** Advanced Level (Power User Patterns) - Guide #7
5+
**Depends On:** `setup-basic-search-params.md`, `navigate-with-search-params.md`
6+
**Status:** Ready for implementation - performance patterns available
7+
8+
---
9+
10+
## Content Staged from navigate-with-search-params.md
11+
12+
### Performance Issues with Functional Updates
13+
14+
**Problem:** Complex functional updates cause unnecessary re-renders.
15+
16+
```tsx
17+
// ❌ Wrong - complex computation in render
18+
<Link search={(prev) => {
19+
// Expensive computation on every render
20+
const result = expensiveCalculation(prev)
21+
return { ...prev, computed: result }
22+
}}>
23+
Update
24+
</Link>
25+
26+
// ✅ Correct - memoize or use callback
27+
const updateSearch = useCallback((prev) => {
28+
const result = expensiveCalculation(prev)
29+
return { ...prev, computed: result }
30+
}, [])
31+
32+
<Link search={updateSearch}>Update</Link>
33+
```
34+
35+
### Navigation During Render
36+
37+
**Problem:** Calling navigate during component render causes infinite loops.
38+
39+
```tsx
40+
function ProblematicComponent() {
41+
const navigate = useNavigate()
42+
43+
// ❌ Wrong - navigate during render
44+
if (someCondition) {
45+
navigate({ search: { redirect: true } })
46+
}
47+
48+
return <div>Content</div>
49+
}
50+
51+
function FixedComponent() {
52+
const navigate = useNavigate()
53+
54+
// ✅ Correct - navigate in effect
55+
useEffect(() => {
56+
if (someCondition) {
57+
navigate({ search: { redirect: true } })
58+
}
59+
}, [someCondition, navigate])
60+
61+
return <div>Content</div>
62+
}
63+
```
64+
65+
---
66+
67+
## Implementation Notes
68+
69+
### Additional Content Needed:
70+
- [ ] Search parameter selectors to prevent unnecessary re-renders
71+
- [ ] Debouncing search input updates
72+
- [ ] Memoization strategies for expensive search computations
73+
- [ ] React.memo usage with search parameters
74+
- [ ] useMemo patterns for derived search state
75+
- [ ] Search parameter batching techniques
76+
- [ ] Performance monitoring and profiling search params
77+
- [ ] Bundle size optimization strategies
78+
79+
### Cross-References to Add:
80+
- Link to `setup-basic-search-params.md` for foundation
81+
- Link to `navigate-with-search-params.md` for navigation patterns
82+
- Link to `search-params-in-forms.md` for debouncing forms
83+
- Forward link to `debug-search-param-issues.md` for debugging performance
84+
85+
### README Update Required:
86+
- [ ] Mark guide as completed in progressive series
87+
- [ ] Uncomment "Common Next Steps" in related guides

0 commit comments

Comments
 (0)