> ## Documentation Index
> Fetch the complete documentation index at: https://cona.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# URL State Parameters with NUQS

> Guide for managing URL state parameters using NUQS

# Guide: URL State Management with nuqs

## Purpose

This guide covers how we use `nuqs` for type-safe URL state management in Next.js 15+ applications. It provides server-side URL parameter parsing with seamless client-side integration.

## Key Principles

### 1. Framework Adapter Required

* Always wrap your app with `NuqsAdapter` from `nuqs/adapters/next`
* Required for Next.js 15+ compatibility

### 2. Server-First Approach

* Parse URL parameters on the server using `createSearchParamsCache`
* Always await `searchParams` in Next.js 15+ page components
* Use `Promise.all` for concurrent async operations

### 3. Type Safety

* Define parsers with proper types and defaults
* Use appropriate parser types: `parseAsString`, `parseAsInteger`, `parseAsBoolean`
* Always provide default values

### 4. Hybrid Usage

* Share parser configurations between server and client components
* Use `useQueryStates` hook for client-side parameter manipulation

## Implementation Overview

### Setup

Install and configure the framework adapter:

```bash theme={null}
pnpm add nuqs@latest
```

### Basic Pattern

#### 1. Create Search Params Configuration

```typescript theme={null}
// app/lib/search-params.ts
export const searchParamsCache = createSearchParamsCache({
  page: parseAsString.withDefault("1"),
  filter: parseAsBoolean.withDefault(false),
});
```

#### 2. Use in Page Components

```typescript theme={null}
// app/page.tsx
export default async function Page(props: { searchParams: Promise<any> }) {
  const searchParams = await props.searchParams;
  await searchParamsCache.parse(searchParams);
  const params = searchParamsCache.all();
  
  return <YourComponent params={params} />;
}
```

#### 3. Client-Side Updates

```typescript theme={null}
// client-component.tsx
"use client";
export function ClientComponent() {
  const [params, setParams] = useQueryStates(parsers);
  // Update URL state as needed
}
```

## Best Practices

### URL Structure

* Use short, semantic parameter names
* Consider URL key mapping for better UX: `pageSize` → `size`
* Keep URLs readable and shareable

### Type Safety

* Always use appropriate parsers for data types
* Add validation constraints when needed
* Provide meaningful default values

### Performance

* Initialize cache at the page level only
* Use concurrent operations with `Promise.all`
* Handle async operations properly in Next.js 15+

## Common Patterns

### Filtering and Pagination

```typescript theme={null}
const searchParamsCache = createSearchParamsCache({
  page: parseAsString.withDefault("1"),
  pageSize: parseAsString.withDefault("10"),
  search: parseAsString.withDefault(""),
});
```

### Boolean Toggles

```typescript theme={null}
const searchParamsCache = createSearchParamsCache({
  showArchived: parseAsBoolean.withDefault(false),
  sortDesc: parseAsBoolean.withDefault(false),
});
```

## Breaking Changes in nuqs 2

* **Framework Adapters**: Must wrap app with `NuqsAdapter`
* **Default Behaviors**: `clearOnDefault` is now `true` by default
* **JSON Parser**: Requires validation function
* **Testing**: Use `NuqsTestingAdapter` for tests

## Key Takeaways

1. **Always use framework adapter** - Required for Next.js 15+
2. **Server-first parsing** - Parse parameters on server, use on client
3. **Type safety matters** - Use proper parsers and defaults
4. **Keep URLs clean** - Use semantic names and consider key mapping
5. **Handle async properly** - Await searchParams and use Promise.all

This approach gives us type-safe, server-rendered URL state that works seamlessly with client-side interactions.