useSearchParams

Returns URL search parameters as a read-only URLSearchParams object. This provides the standard web API for working with query strings.

Basic Usage

import { useSearchParams } from 'one'

// URL: /products?sort=price&category=electronics

export default function Products() {
  const searchParams = useSearchParams()

  const sort = searchParams.get('sort')           // 'price'
  const category = searchParams.get('category')   // 'electronics'
  const missing = searchParams.get('missing')     // null

  return <Text>Sorted by {sort}</Text>
}

URLSearchParams Methods

The returned object supports all standard URLSearchParams read methods:

const searchParams = useSearchParams()

// Get a single value
searchParams.get('key')        // string | null

// Check if param exists
searchParams.has('key')        // boolean

// Get all values for a key (for repeated params)
searchParams.getAll('tag')     // string[]

// Iterate over all entries
for (const [key, value] of searchParams) {
  console.log(key, value)
}

// Convert to string
searchParams.toString()        // 'key=value&other=123'

Repeated Parameters

Use getAll() when a parameter appears multiple times:

// URL: /filter?tag=react&tag=typescript&tag=native

const searchParams = useSearchParams()
const tags = searchParams.getAll('tag')
// tags = ['react', 'typescript', 'native']

Global Option

By default, useSearchParams only updates when the current route is focused. Pass { global: true } to update on any route change:

// Updates even when this screen is not focused
const searchParams = useSearchParams({ global: true })

The global option cannot change between renders.

Read-Only

The returned URLSearchParams is read-only. Calling set(), append(), or delete() will throw an error:

const searchParams = useSearchParams()

// ❌ These will throw
searchParams.set('key', 'value')
searchParams.append('key', 'value')
searchParams.delete('key')

To update search params, use the router:

import { useRouter, useSearchParams } from 'one'

function Filters() {
  const router = useRouter()
  const searchParams = useSearchParams()

  const updateSort = (sort: string) => {
    // Build new search string
    const params = new URLSearchParams(searchParams)
    params.set('sort', sort)

    router.push(`/products?${params.toString()}`)
  }
}