검색 매개변수로 탐색하는 방법

이 가이드에서는 TanStack Router의 Link 컴포넌트와 프로그래밍 방식 탐색 메서드를 사용하여 탐색 중 검색 매개변수를 업데이트하고 관리하는 방법을 설명합니다.

사전 요구 사항: 기본 검색 매개변수 설정 - 검색 매개변수를 읽고 검증하기 위한 기초 개념입니다.

빠른 시작

기존 상태를 유지하면서 검색 매개변수를 업데이트하는 탐색을 구성합니다.

import { Link, useNavigate } from '@tanstack/react-router'

// Link with search parameter updates
;<Link to="/search" search={(prev) => ({ ...prev, query: 'new search' })}>
  Search for "new search"
</Link>

// Programmatic navigation
const navigate = useNavigate()
navigate({
  to: '/search',
  search: (prev) => ({ ...prev, page: 1 }),
})

탐색 메서드

Link 컴포넌트 사용

기본 검색 매개변수 업데이트

모든 검색 매개변수를 교체합니다.

import { Link } from '@tanstack/router'

function SearchForm() {
  return (
    <div>
      {/* Replace all search params */}
      <Link to="/products" search={{ category: 'electronics', page: 1 }}>
        Electronics
      </Link>

      {/* Navigate to same route with new search */}
      <Link search={{ sort: 'price-asc' }}>Sort by Price</Link>
    </div>
  )
}

함수형 검색 매개변수 업데이트

기존 검색 매개변수와 병합합니다.

import { Link } from '@tanstack/react-router'

function Pagination() {
  return (
    <div>
      {/* Preserve existing search, update page */}
      <Link search={(prev) => ({ ...prev, page: (prev.page || 1) + 1 })}>
        Next Page
      </Link>

      {/* Toggle filter while keeping other params */}
      <Link
        search={(prev) => ({
          ...prev,
          inStock: !prev.inStock,
        })}
      >
        Toggle In Stock
      </Link>

      {/* Remove a search parameter */}
      <Link
        search={(prev) => {
          const { category, ...rest } = prev
          return rest
        }}
      >
        Clear Category Filter
      </Link>
    </div>
  )
}

모든 검색 매개변수 유지

탐색할 때 현재 검색 매개변수를 모두 유지하려면 search={true}를 사용합니다.

import { Link } from '@tanstack/react-router'

function Navigation() {
  return (
    <nav>
      {/* Keep all search params when changing routes */}
      <Link to="/products" search={true}>
        View Products (Keep Filters)
      </Link>

      {/* Equivalent functional approach */}
      <Link to="/products" search={(prev) => prev}>
        View Products (Functional)
      </Link>
    </nav>
  )
}

라우트 변경을 포함한 탐색

검색 매개변수를 사용하여 다른 라우트로 이동합니다.

import { Link } from '@tanstack/react-router'

function Navigation() {
  return (
    <nav>
      {/* Navigate to different route with search */}
      <Link to="/search" search={{ query: 'laptops', category: 'electronics' }}>
        Search Laptops
      </Link>

      {/* Inherit current search params to new route */}
      <Link
        to="/products"
        search={true} // Shorthand to carry over all search params
      >
        View Products
      </Link>

      {/* Transform search params for new route */}
      <Link
        to="/advanced-search"
        search={(prev) => ({
          q: prev.query, // Rename parameter
          filters: {
            category: prev.category,
            inStock: prev.inStock,
          },
        })}
      >
        Advanced Search
      </Link>
    </nav>
  )
}

프로그래밍 방식 탐색

useNavigate 훅 사용

검색 매개변수를 업데이트하면서 프로그래밍 방식으로 이동합니다.

import { useNavigate } from '@tanstack/react-router'

function SearchControls() {
  const navigate = useNavigate()

  const handleSortChange = (sortBy: string) => {
    navigate({
      search: (prev) => ({ ...prev, sort: sortBy, page: 1 }),
    })
  }

  const handleClearFilters = () => {
    navigate({
      search: (prev) => {
        const { category, minPrice, maxPrice, ...rest } = prev
        return rest
      },
    })
  }

  const handleSearch = (query: string) => {
    navigate({
      to: '/search',
      search: { query, page: 1 },
    })
  }

  return (
    <div>
      <select onChange={(e) => handleSortChange(e.target.value)}>
        <option value="relevance">Sort by Relevance</option>
        <option value="price-asc">Price: Low to High</option>
        <option value="price-desc">Price: High to Low</option>
      </select>

      <button onClick={handleClearFilters}>Clear Filters</button>

      <button onClick={() => handleSearch('latest products')}>
        Search Latest
      </button>
    </div>
  )
}

라우터 인스턴스를 사용한 탐색

useNavigate 또는 Link를 사용할 수 없는 React 외부 컨텍스트에서만 라우터를 직접 사용합니다.

import { router } from './router' // Your router instance

// ✅ Appropriate use case: Utility function outside React components
export function navigateFromUtility(searchParams: Record<string, any>) {
  router.navigate({
    search: (prev) => ({ ...prev, ...searchParams }),
  })
}

// ✅ Appropriate use case: Event handlers in non-React code
class ApiService {
  onAuthError() {
    // Navigate to login when auth fails
    router.navigate({
      to: '/login',
      search: { redirect: window.location.pathname },
    })
  }
}

// ✅ Appropriate use case: Global error handler
window.addEventListener('unhandledrejection', (event) => {
  if (event.reason.status === 401) {
    router.navigate({
      to: '/login',
      search: { error: 'session-expired' },
    })
  }
})

⚠️ React 컴포넌트에서는 대신 useNavigate를 사용하는 것을 권장합니다.

// ❌ Avoid in React components
function Component() {
  const router = useRouter()

  const handleClick = () => {
    router.navigate({ search: { filter: 'active' } })
  }

  return <button onClick={handleClick}>Filter</button>
}

// ✅ Use useNavigate in React components
function Component() {
  const navigate = useNavigate()

  const handleClick = () => {
    navigate({ search: { filter: 'active' } })
  }

  return <button onClick={handleClick}>Filter</button>
}

고급 탐색 패턴

조건부 탐색

특정 조건이 충족되면 자동으로 이동합니다.

import { useEffect } from 'react'
import { useNavigate, useSearch } from '@tanstack/react-router'

function ConditionalNavigation() {
  const navigate = useNavigate()
  const search = useSearch({ from: '/products' })

  // Auto-reset page when search query changes
  useEffect(() => {
    if (search.query && search.page > 1) {
      navigate({
        search: (prev) => ({ ...prev, page: 1 }),
      })
    }
  }, [search.query, search.page, navigate])

  return <div>Page resets automatically when search changes</div>
}

일반적인 패턴

일반적인 문제

검색 매개변수가 업데이트되지 않음

문제: Link 탐색이 검색 매개변수를 업데이트하지 않습니다.

// ❌ Wrong - no search prop
<Link to="/products">Electronics</Link>

// ✅ Correct - with search parameters
<Link to="/products" search={{ category: 'electronics' }}>
  Electronics
</Link>

기존 검색 매개변수 손실

문제: 새 탐색이 특정 매개변수만 업데이트하지 않고 모든 검색 매개변수를 교체합니다.

// ❌ Wrong - replaces all search params
<Link search={{ page: 2 }}>Next Page</Link>

// ✅ Correct - preserves existing search params
<Link search={(prev) => ({ ...prev, page: 2 })}>
  Next Page
</Link>

일반적인 다음 단계

검색 매개변수를 사용한 탐색을 익힌 후에는 다음 작업을 고려할 수 있습니다.

• 스키마로 검색 매개변수 검증 - Zod, Valibot 또는 ArkType으로 강력한 검증을 추가합니다.
• 배열, 객체 및 날짜 작업 - 배열, 객체, 날짜 및 중첩 데이터 구조를 처리합니다.

관련 리소스

• TanStack Router 검색 매개변수 가이드 - 공식 문서