### Install nuqs-svelte with pnpm, yarn, or npm

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

These commands show how to install the nuqs-svelte package using different package managers. Ensure you have one of them installed to manage your project's dependencies.

```shell
pnpm add nuqs-svelte
```

```shell
yarn add nuqs-svelte
```

```shell
npm install nuqs-svelte
```

--------------------------------

### SvelteKit Adapter Setup for nuqs-svelte

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

This Svelte component demonstrates how to integrate nuqs-svelte with SvelteKit by wrapping the application's children with the NuqsAdapter. This is necessary for routing and state management to function correctly within a SvelteKit project.

```svelte
// src/routes/+layout.svelte
<script lang="ts">
  import { NuqsAdapter } from "nuqs-svelte/adapters/svelte-kit";
  import "../app.css";

  let { children } = $props();
</script>

<NuqsAdapter>
  {@render children()}
</NuqsAdapter>
```

--------------------------------

### Creating Custom Parsers in TypeScript

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Illustrates how to create custom parsers using createParser and compose them with existing parsers. This example creates a hex color parser that parses RGB values from a 6-character hex string. The parser can be configured with common options like history behavior.

```typescript
import { createParser, parseAsHex } from "nuqs-svelte";

// Wrapping your parser/serializer in `createParser`
// gives it access to the builder pattern & server-side
// parsing capabilities:
const hexColorSchema = createParser({
  parse(query) {
    if (query.length !== 6) {
      return null; // always return null for invalid inputs
    }
    return {
      // When composing other parsers, they may return null too.
      r: parseAsHex.parse(query.slice(0, 2)) ?? 0x00,
      g: parseAsHex.parse(query.slice(2, 4)) ?? 0x00,
      b: parseAsHex.parse(query.slice(4)) ?? 0x00,
    };
  },
  serialize({ r, g, b }) {
    return parseAsHex.serialize(r) + parseAsHex.serialize(g) + parseAsHex.serialize(b);
  },
})
  // Eg: set common options directly
  .withOptions({ history: "push" });

// Or on usage:
useQueryState(
  "tribute",
  hexColorSchema.withDefault({
    r: 0x66,
    g: 0x33,
    b: 0x99,
  }),
);
```

--------------------------------

### Generate Dynamic Canonical URL with Query String

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

When query strings define page content (e.g., video URLs), the canonical URL should include relevant parameters. This example shows how to dynamically generate a canonical URL using `generateMetadata` and `useQueryState` in Next.js.

```typescript
// page.tsx
import type { Metadata, ResolvingMetadata } from "next";
import { useQueryState } from "nuqs";
import { parseAsString } from "nuqs/server";

type Props = {
  searchParams: { [key: string]: string | string[] | undefined };
};

export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
  const videoId = parseAsString.parseServerSide(searchParams.v);
  return {
    alternates: {
      canonical: `/watch?v=${videoId}`,
    },
  };
}

```

--------------------------------

### Configuring Parsers with Builder Pattern in TypeScript

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Shows how to use the builder pattern to configure parsers with default values and options. This example uses parseAsInteger with a default value of 0 and history option set to 'push'. Custom parsers can also be created and composed with existing ones.

```typescript
useQueryState(
  "counter",
  parseAsInteger.withDefault(0).withOptions({
    history: "push",
    shallow: false,
  }),
);
```

--------------------------------

### Awaiting Query State Updates in TypeScript

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Shows how to await the Promise returned by state updater functions to get the updated URLSearchParams object. This allows you to know when the URL has been updated and access the current parameter values. Batched updates are merged and flushed once to the URL.

```typescript
const randomCoordinates = () => {
  setLat(42);
  return setLng(12);
};

randomCoordinates().then((search: URLSearchParams) => {
  search.get("lat"); // 42
  search.get("lng"); // 12, has been queued and batch-updated
});
```

--------------------------------

### Nuqs Shareable Parsers for Client and Server Components

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Illustrates sharing parser definitions between server and client components using 'nuqs/server'. It demonstrates accessing all parameters or individual ones in server components and using 'useQueryStates' in client components.

```tsx
// searchParams.ts
import { parseAsFloat, createSearchParamsCache } from "nuqs/server";

export const coordinatesParsers = {
  lat: parseAsFloat.withDefault(45.18),
  lng: parseAsFloat.withDefault(5.72),
};
export const coordinatesCache = createSearchParamsCache(coordinatesParsers);

// page.tsx
import { coordinatesCache } from "./searchParams";
import { Server } from "./server";
import { Client } from "./client";

export default async function Page({ searchParams }) {
  await coordinatesCache.parse(searchParams);
  return (
    <>
      <Server />
      <Suspense>
        <Client />
      </Suspense>
    </>
  );
}

// server.tsx
import { coordinatesCache } from "./searchParams";

export function Server() {
  const { lat, lng } = coordinatesCache.all();
  // or access keys individually:
  const lat = coordinatesCache.get("lat");
  const lng = coordinatesCache.get("lng");
  return (
    <span>
      Latitude: {lat} - Longitude: {lng}
    </span>
  );
}

// client.tsx
// prettier-ignore
'use client'

import { useQueryStates } from "nuqs";
import { coordinatesParsers } from "./searchParams";

export function Client() {
  const [{ lat, lng }, setCoordinates] = useQueryStates(coordinatesParsers);
  // ...
}
```

--------------------------------

### Unit Test Components with `NuqsTestingAdapter`

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

The `NuqsTestingAdapter` allows for isolated unit testing of components that use `useQueryState` or `useQueryStates`. It integrates with testing frameworks like Vitest and Testing Library, enabling mocking of initial search parameters and capturing URL update events.

```tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { NuqsTestingAdapter, type UrlUpdateEvent } from "nuqs/adapters/testing";
import { describe, expect, it, vi } from "vitest";
import { CounterButton } from "./counter-button";

it("should increment the count when clicked", async () => {
  const user = userEvent.setup();
  const onUrlUpdate = vi.fn<[UrlUpdateEvent]>();
  render(<CounterButton />, {
    // Setup the test by passing initial search params / querystring,
    // and give it a function to call on URL updates
    wrapper: ({ children }) => (
      <NuqsTestingAdapter searchParams="?count=42" onUrlUpdate={onUrlUpdate}>
        {children}
      </NuqsTestingAdapter>
    ),
  });
  // Initial state assertions: there's a clickable button displaying the count
  const button = screen.getByRole("button");
  expect(button).toHaveTextContent("count is 42");
  // Act
  await user.click(button);
  // Assert changes in the state and in the (mocked) URL
  expect(button).toHaveTextContent("count is 43");
  expect(onUrlUpdate).toHaveBeenCalledOnce();
  expect(onUrlUpdate.mock.calls[0][0].queryString).toBe("?count=43");
  expect(onUrlUpdate.mock.calls[0][0].searchParams.get("count")).toBe("43");
  expect(onUrlUpdate.mock.calls[0][0].options.history).toBe("push");
});
```

--------------------------------

### Nuqs Serializer Helper for Link Generation

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Explains how to use the 'createSerializer' helper from 'nuqs/server' to generate query strings for URL parameters. It allows defining search param structures and serializing values into a query string format compatible with nuqs hooks.

```ts
import {
  createSerializer,
  parseAsInteger,
  parseAsIsoDateTime,
  parseAsString,
  parseAsStringLiteral,
} from "nuqs/server";

const searchParams = {
  search: parseAsString,
  limit: parseAsInteger,
  from: parseAsIsoDateTime,
  to: parseAsIsoDateTime,
  sortBy: parseAsStringLiteral(["asc", "desc"] as const),
};

// Create a serializer function by passing the description of the search params to accept
const serialize = createSerializer(searchParams);

// Then later, pass it some values (a subset) and render them to a query string
serialize({
  search: "foo bar",
  limit: 10,
  from: new Date("2024-01-01"),
  // here, we omit `to`, which won't be added
  sortBy: null, // null values are also not rendered
});
// ?search=foo+bar&limit=10&from=2024-01-01T00:00:00.000Z
```

--------------------------------

### Create Custom Query Parsers with Serialization and Equality (Svelte)

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Shows how to create custom query string parsers using `createParser` from `nuqs-svelte`. This allows full control over parsing, serialization, and equality checking for complex data types.

```svelte
<script lang="ts">
  import { useQueryState, createParser, parseAsHex } from "nuqs-svelte";

  type RGB = { r: number; g: number; b: number };

  const hexColorParser = createParser<RGB>({
    parse(query: string): RGB | null {
      if (query.length !== 6) return null;

      const r = parseInt(query.slice(0, 2), 16);
      const g = parseInt(query.slice(2, 4), 16);
      const b = parseInt(query.slice(4, 6), 16);

      if (isNaN(r) || isNaN(g) || isNaN(b)) return null;

      return { r, g, b };
    },

    serialize(value: RGB): string {
      const toHex = (n: number) => n.toString(16).padStart(2, "0");
      return toHex(value.r) + toHex(value.g) + toHex(value.b);
    },

    eq(a: RGB, b: RGB): boolean {
      return a.r === b.r && a.g === b.g && a.b === b.b;
    }
  });

  const color = useQueryState(
    "color",
    hexColorParser.withDefault({ r: 255, g: 0, b: 0 })
  );

  // URL: /?color=ff0000 → color.current = { r: 255, g: 0, b: 0 }

  const hexString = $derived(
    color.current.r.toString(16).padStart(2, "0") +
    color.current.g.toString(16).padStart(2, "0") +
    color.current.b.toString(16).padStart(2, "0")
  );
</script>

<div>
  <input type="number" bind:value={color.current.r} min="0" max="255" />
  <input type="number" bind:value={color.current.g} min="0" max="255" />
  <input type="number" bind:value={color.current.b} min="0" max="255" />

  <div style="background: #{hexString}; width: 100px; height: 100px;"></div>
  <p>Hex: #{hexString}</p>
</div>
```

--------------------------------

### Create One-Off Search Param Loader with Nuqs

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Demonstrates how to create a loader function using 'nuqs' to parse search parameters from a URL string. It supports various input types and allows defining default values for parameters.

```tsx
import { createLoader } from "nuqs"; // or 'nuqs/server'

const searchParams = {
  q: parseAsString,
  page: parseAsInteger.withDefault(1),
};

const loadSearchParams = createLoader(searchParams);

const { q, page } = loadSearchParams("?q=hello&page=2");
```

--------------------------------

### Implement Integer Query State Parsing with Pagination in Svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Parses URL query parameters as integers for pagination using parseAsInteger. Uses useQueryState hook with default values for page and limit. Calculates offset reactively and provides next/previous page navigation with history push.

```svelte
<script lang="ts">
  import { useQueryState, parseAsInteger } from "nuqs-svelte";

  const page = useQueryState("page", parseAsInteger.withDefault(1));
  const limit = useQueryState("limit", parseAsInteger.withDefault(20));

  // URL: /?page=3&limit=50
  // page.current = 3, limit.current = 50

  const offset = $derived((page.current - 1) * limit.current);

  function nextPage() {
    page.set(p => p + 1, { history: "push" });
  }

  function prevPage() {
    if (page.current > 1) {
      page.set(p => p - 1, { history: "push" });
    }
  }
</script>

<div>
  <p>Page {page.current} | Showing {limit.current} items</p>
  <p>Offset: {offset}</p>
  <button onclick={prevPage} disabled={page.current <= 1}>Previous</button>
  <button onclick={nextPage}>Next</button>

  <select bind:value={limit.current}>
    <option value={10}>10</option>
    <option value={20}>20</option>
    <option value={50}>50</option>
    <option value={100}>100</option>
  </select>
</div>
```

--------------------------------

### Basic Usage of useQueryState in nuqs-svelte

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

This Svelte component illustrates the fundamental usage of the `useQueryState` hook from nuqs-svelte. It binds an input field to a query parameter named 'name', allowing for two-way data binding between the input's value and the URL's query string.

```svelte
// src/routes/+page.svelte
<script lang="ts">
  import { useQueryState } from "nuqs-svelte";
  import "../app.css";

  const name = useQueryState("name");
</script>

<h1>Hello, {name.current || "anonymous visitor"}!</h1>
<input bind:value={name.current} />
<button onclick={() => name.current = null}>Clear</button>
```

--------------------------------

### Configuring Nuqs-Svelte Options for Behavior Customization

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Demonstrates how to configure URL update behavior at adapter-wide, hook-level, or per-update using various options like history, scroll, throttleMs, and clearOnDefault.

```svelte
<script lang="ts">
  import { useQueryState, useQueryStates, parseAsString, parseAsInteger } from "nuqs-svelte";

  // Per-parser options (highest priority at call site)
  const modal = useQueryState(
    "modal",
    parseAsString.withOptions({
      history: "push",      // Create history entry (enables back button)
      scroll: false,        // Don't scroll to top
      clearOnDefault: true  // Remove param when equals default
    })
  );

  // Per-hook options
  const filters = useQueryStates(
    {
      search: parseAsString,
      category: parseAsString,
    },
    {
      throttleMs: 300,  // Wait 300ms before updating URL
      shallow: true     // SvelteKit: client-side only
    }
  );

  // Per-call options (override everything)
  function openModal(id: string) {
    modal.set(id, {
      history: "push",
      scroll: true  // Override default scroll behavior
    });
  }

  function updateFilters() {
    filters.set(
      { search: "laptop", category: "electronics" },
      { history: "replace" }  // Don't create history entry
    );
  }
</script>

<!--
Option Priority (high to low):
1. Per-call options in set()
2. Parser withOptions()
3. Hook-level options
4. Adapter-level options
-->
```

--------------------------------

### Manage Single Query Parameter with useQueryState (Svelte)

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Manages a single query parameter in the URL using type-safe parsing and reactivity. It allows setting default values and updating the URL with history management. Dependencies include 'nuqs-svelte' and its parsing functions.

```svelte
<script lang="ts">
  import { useQueryState, parseAsInteger, parseAsString } from "nuqs-svelte";

  // Basic usage with integer parser and default value
  const count = useQueryState("count", parseAsInteger.withDefault(0));

  // String parser (default)
  const search = useQueryState("q", parseAsString.withDefault(""));

  // URL: /?count=5&q=hello
  // count.current = 5, search.current = "hello"

  function increment() {
    count.set(c => c + 1, { history: "push" }); // Creates history entry
  }

  function reset() {
    count.set(0); // Returns to default, removes param from URL
  }
</script>

<input bind:value={search.current} placeholder="Search..." />
<p>Count: {count.current}</p>
<button onclick={increment}>Increment</button>
<button onclick={reset}>Reset</button>

```

--------------------------------

### NuqsAdapter for SvelteKit Integration

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Integrates nuqs-svelte with SvelteKit's routing system. It wraps the application's content and applies specified options for history management, shallow routing, and scrolling behavior.

```svelte
<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { NuqsAdapter } from "nuqs-svelte/adapters/svelte-kit";

  let { children } = $props();
</script>

<NuqsAdapter options={{
  history: "replace",
  shallow: true,
  scroll: false,
  throttleMs: 50,
  clearOnDefault: true
}}>
  {@render children()}
</NuqsAdapter>
```

```svelte
<!-- src/routes/search/+page.svelte -->
<script lang="ts">
  import { useQueryStates, parseAsString, parseAsArrayOf, parseAsInteger } from "nuqs-svelte";

  const searchParams = useQueryStates({
    q: parseAsString.withDefault(""),
    categories: parseAsArrayOf(parseAsString).withDefault([]),
    page: parseAsInteger.withDefault(1),
  });

  // URL updates use SvelteKit's goto() and are shallow by default
  // Set shallow: false to trigger server-side loaders
</script>

<input bind:value={searchParams.q.current} />
```

--------------------------------

### Manage Multiple Query Parameters with useQueryStates (Svelte)

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Manages multiple related query parameters atomically using 'useQueryStates'. This function allows defining and synchronizing several parameters, such as location coordinates and zoom level, with built-in type safety and configurable update options. Dependencies include 'nuqs-svelte' and its parsing functions.

```svelte
<script lang="ts">
  import { useQueryStates, parseAsFloat, parseAsString, parseAsInteger } from "nuqs-svelte";

  // Define multiple related parameters
  const location = useQueryStates({
    lat: parseAsFloat.withDefault(45.18),
    lng: parseAsFloat.withDefault(5.72),
    zoom: parseAsInteger.withDefault(12),
    address: parseAsString.withDefault(""),
  });

  // URL: /?lat=40.7128&lng=-74.0060&zoom=10&address=New+York

  function updateLocation(newLat: number, newLng: number) {
    // Atomic update of multiple values
    location.set(
      { lat: newLat, lng: newLng, address: null },
      { history: "push", scroll: false }
    );
  }

  function resetToDefault() {
    location.set({
      lat: 45.18,
      lng: 5.72,
      zoom: 12,
      address: "",
    });
  }
</script>

<div>
  <input type="number" bind:value={location.lat.current} step="0.0001" />
  <input type="number" bind:value={location.lng.current} step="0.0001" />
  <input type="number" bind:value={location.zoom.current} />
  <input bind:value={location.address.current} placeholder="Address" />
</div>

<button onclick={() => updateLocation(40.7128, -74.0060)}>New York</button>
<button onclick={resetToDefault}>Reset</button>

```

--------------------------------

### NuqsAdapter for Vanilla Svelte Integration

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Integrates nuqs-svelte with vanilla Svelte applications using native browser APIs. This adapter is suitable for any Svelte 5 application not using SvelteKit.

```svelte
<!-- src/App.svelte -->
<script lang="ts">
  import { NuqsAdapter } from "nuqs-svelte/adapters/native";
  import SearchPage from "./SearchPage.svelte";
</script>

<NuqsAdapter options={{
  history: "push",
  scroll: false,
  throttleMs: 50
}}>
  <SearchPage />
</NuqsAdapter>
```

```svelte
<!-- src/SearchPage.svelte -->
<script lang="ts">
  import { useQueryState, parseAsString } from "nuqs-svelte";

  const query = useQueryState("q", parseAsString.withDefault(""));

  // URL updates use native window.history API
  // Works with any Svelte 5 application (Vite, etc.)
</script>

<input bind:value={query.current} placeholder="Search..." />
```

--------------------------------

### Generate Query Strings Programmatically with Custom Parsers (Svelte)

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Illustrates the use of `createSerializer` from `nuqs-svelte` to generate query strings from values. This is useful for creating navigation links and programmatic URL manipulation.

```svelte
<script lang="ts">
  import { createSerializer, parseAsString, parseAsInteger, parseAsIsoDateTime } from "nuqs-svelte";

  const serialize = createSerializer({
    search: parseAsString,
    page: parseAsInteger,
    limit: parseAsInteger,
    from: parseAsIsoDateTime,
    to: parseAsIsoDateTime,
  });

  // Generate query string
  const queryString = serialize({
    search: "foo bar",
    page: 2,
    limit: 20,
    from: new Date("2024-01-01"),
    to: null, // Omits parameter
  });
  // Returns: "?search=foo+bar&page=2&limit=20&from=2024-01-01T00:00:00.000Z"

  // Append to existing path
  const url = serialize("/products", {
    search: "laptop",
    page: 1,
  });
  // Returns: "/products?search=laptop&page=1"

  // Merge with existing query params
  const mergedUrl = serialize("/api?existing=true", {
    search: "new value",
  });
  // Returns: "/api?existing=true&search=new+value"
</script>

<nav>
  <a href={serialize("/products", { search: "laptop", page: 1 })}>
    Laptops - Page 1
  </a>

  <a href={serialize("/products", { search: "phone", page: 1 }) }>
    Phones - Page 1
  </a>

  <a href={serialize("/products", {
    search: "tablet",
    page: 1,
    from: new Date("2024-01-01"),
  })}>
    Tablets (since 2024)
  </a>
</nav>
```

--------------------------------

### Implement Float Query State Parsing for Numeric Ranges in Svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Parses URL query parameters as floating-point numbers using parseAsFloat. Demonstrates price and rating range inputs with reactive tax and total calculations based on price value.

```svelte
<script lang="ts">
  import { useQueryState, parseAsFloat } from "nuqs-svelte";

  const price = useQueryState("price", parseAsFloat.withDefault(0));
  const rating = useQueryState("rating", parseAsFloat.withDefault(0));

  // URL: /?price=29.99&rating=4.5
  // price.current = 29.99, rating.current = 4.5

  const tax = $derived(price.current * 0.1);
  const total = $derived(price.current + tax);
</script>

<div>
  <label>
    Price: ${price.current}
    <input type="range" bind:value={price.current} min="0" max="100" step="0.01" />
  </label>

  <label>
    Rating: {rating.current} / 5
    <input type="range" bind:value={rating.current} min="0" max="5" step="0.1" />
  </label>

  <p>Tax: ${tax.toFixed(2)}</p>
  <p>Total: ${total.toFixed(2)}</p>
</div>
```

--------------------------------

### Batching Multiple Query Updates in Svelte

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Demonstrates how to perform multiple query state updates in a single event loop tick. The updates are batched and applied asynchronously to the URL. Each state setter function returns a Promise that resolves with the updated URLSearchParams object.

```svelte
<script lang="ts">
  const lat = useQueryState("lat", parseAsFloat);
  const lng = useQueryState("lng", parseAsFloat);

  const randomCoordinates = () => {
    lat.set(Math.random() * 180 - 90);
    lng.set(Math.random() * 360 - 180);
  }
</script>
```

--------------------------------

### Handle Invalid Inputs and Errors with nuqs-svelte Parsers

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Demonstrates how nuqs-svelte parsers handle invalid inputs by returning null, and how to use default values or runtime validation with try-catch blocks to manage error scenarios gracefully. This ensures a more robust user experience when dealing with potentially malformed URL query parameters.

```svelte
<script lang="ts">
  import { useQueryState, parseAsInteger, parseAsStringEnum } from "nuqs-svelte";

  // Parsers don't throw - they return null for invalid input
  const age = useQueryState("age", parseAsInteger);
  // URL: /?age=abc → age.current = null (invalid integer)
  // URL: /?age=25 → age.current = 25 (valid)

  // Use defaults to handle null values
  const safeAge = useQueryState("age", parseAsInteger.withDefault(0));
  // URL: /?age=abc → safeAge.current = 0 (falls back to default)

  // Enum validation
  enum Status { Active = "active", Inactive = "inactive" }
  const status = useQueryState(
    "status",
    parseAsStringEnum<Status>(Object.values(Status)).withDefault(Status.Active)
  );
  // URL: /?status=invalid → status.current = "active" (falls back to default)

  // Runtime validation with try-catch
  function validateAndSet(value: string) {
    try {
      const parsed = parseInt(value);
      if (isNaN(parsed) || parsed < 0 || parsed > 120) {
        throw new Error("Age must be between 0 and 120");
      }
      age.set(parsed);
    } catch (error) {
      console.error("Validation failed:", error);
      // Keep current value, show error to user
    }
  }
</script>

<div>
  <input
    value={age.current ?? ""}
    oninput={(e) => validateAndSet(e.currentTarget.value)}
    placeholder="Enter age"
  />
  {#if age.current === null}
    <p class="error">Invalid age value in URL</p>
  {/if}
</div>

```

--------------------------------

### Batch Multiple State Updates in Svelte with nuqs-svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Demonstrates how nuqs-svelte automatically batches multiple state updates within the same tick into a single URL update, optimizing performance. It also shows how to perform atomic updates for guaranteed single URL changes using `useQueryStates`.

```svelte
<script lang="ts">
  import { useQueryStates, parseAsFloat, parseAsInteger } from "nuqs-svelte";

  const map = useQueryStates({
    lat: parseAsFloat.withDefault(0),
    lng: parseAsFloat.withDefault(0),
    zoom: parseAsInteger.withDefault(10),
  });

  // These updates are batched into single URL change
  function flyToLocation(lat: number, lng: number, zoom: number) {
    map.lat.set(lat);
    map.lng.set(lng);
    map.zoom.set(zoom);
    // Only one URL update happens after all three sets
  }

  // Atomic update is more explicit
  function flyToLocationAtomic(lat: number, lng: number, zoom: number) {
    map.set({ lat, lng, zoom }, { history: "push" });
    // Guaranteed single URL update
  }

  const cities = [
    { name: "Paris", lat: 48.8566, lng: 2.3522, zoom: 12 },
    { name: "Tokyo", lat: 35.6762, lng: 139.6503, zoom: 11 },
    { name: "New York", lat: 40.7128, lng: -74.0060, zoom: 10 },
  ];
</script>

<div>
  {#each cities as city}
    <button onclick={() => flyToLocation(city.lat, city.lng, city.zoom)}>
      {city.name}
    </button>
  {/each}
</div>

```

--------------------------------

### Parse ISO DateTime in Svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Demonstrates parsing query parameters as ISO-8601 datetime strings using parseAsIsoDateTime from nuqs-svelte. Implements date range selection with default values and computed duration between dates. Includes UI controls with datetime-local inputs and a button to set the last 7 days range.

```svelte
<script lang="ts">
  import { useQueryState, parseAsIsoDateTime } from "nuqs-svelte";

  const startDate = useQueryState(
    "start",
    parseAsIsoDateTime.withDefault(new Date("2024-01-01T00:00:00Z"))
  );
  const endDate = useQueryState(
    "end",
    parseAsIsoDateTime.withDefault(new Date())
  );

  // URL: /?start=2024-01-01T00:00:00.000Z&end=2024-12-31T23:59:59.999Z

  const duration = $derived(
    endDate.current.getTime() - startDate.current.getTime()
  );
  const durationDays = $derived(Math.floor(duration / (1000 * 60 * 60 * 24)));

  function setLastWeek() {
    const end = new Date();
    const start = new Date(end);
    start.setDate(start.getDate() - 7);
    startDate.set(start);
    endDate.set(end);
  }
</script>

<div>
  <input
    type="datetime-local"
    value={startDate.current.toISOString().slice(0, 16)}
    onchange={(e) => startDate.current = new Date(e.currentTarget.value)} />

  <input
    type="datetime-local"
    value={endDate.current.toISOString().slice(0, 16)}
    onchange={(e) => endDate.current = new Date(e.currentTarget.value)} />

  <p>Duration: {durationDays} days</p>
  <button onclick={setLastWeek}>Last 7 Days</button>
</div>
```

--------------------------------

### Using useQueryStates Hook in TypeScript

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Demonstrates how to use the useQueryStates hook for managing multiple related query parameters as a single unit. This approach ensures that related parameters are updated together and provides a convenient way to set multiple keys at once. The hook returns individual state variables and a combined setter function.

```typescript
import { useQueryStates, parseAsFloat } from "nuqs-svelte";

const coordinates = useQueryStates(
  {
    lat: parseAsFloat.withDefault(45.18),
    lng: parseAsFloat.withDefault(5.72),
  },
  {
    history: "push",
  },
);

const { lat, lng } = coordinates;

// Set all (or a subset of) the keys in one go:
const search = await coordinates.set({
  lat: Math.random() * 180 - 90,
  lng: Math.random() * 360 - 180,
});
```

--------------------------------

### Synchronize State Across Svelte Components with nuqs-svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Illustrates how multiple Svelte components can observe and update the same query parameter, ensuring automatic synchronization across the application. This pattern is facilitated by nuqs-svelte's underlying event emitter mechanism, simplifying global state management.

```svelte
<!-- Component A -->
<script lang="ts">
  import { useQueryState, parseAsInteger } from "nuqs-svelte";

  const count = useQueryState("count", parseAsInteger.withDefault(0));
</script>

<div>
  <p>Component A: {count.current}</p>
  <button onclick={() => count.set(c => c + 1)}>Increment from A</button>
</div>

<!-- Component B (in different part of app) -->
<script lang="ts">
  import { useQueryState, parseAsInteger } from "nuqs-svelte";

  const count = useQueryState("count", parseAsInteger.withDefault(0));
  // Automatically synced with Component A's count!
</script>

<div>
  <p>Component B: {count.current}</p>
  <button onclick={() => count.set(c => c + 1)}>Increment from B</button>
</div>

<!-- Both components stay in sync via event emitter pattern -->

```

--------------------------------

### String Query Parameter Parsing with parseAsString (Svelte)

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Provides a string parser for managing query parameters as strings, with support for default values and custom options like history management. This function is part of the 'nuqs-svelte' library and is used with 'useQueryState' or 'useQueryStates'.

```svelte
<script lang="ts">
  import { useQueryState, parseAsString } from "nuqs-svelte";

  // Basic string parser
  const name = useQueryState("name", parseAsString);
  // URL: /?name=John → name.current = "John"
  // URL: / → name.current = null

  // With default value
  const category = useQueryState("cat", parseAsString.withDefault("all"));
  // URL: / → category.current = "all"

  // With options
  const filter = useQueryState(
    "filter",
    parseAsString.withDefault("").withOptions({ history: "push" })
  );
</script>

<input bind:value={name.current} />
<select bind:value={category.current}>
  <option value="all">All</option>
  <option value="tech">Technology</option>
  <option value="science">Science</option>
</select>

```

--------------------------------

### Nuqs Server Component Search Params Cache

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Shows how to use 'nuqs/server' to create a type-safe cache for search parameters within Server Components. It includes parsing search params and accessing them in child components.

```tsx
// searchParams.ts
import { createSearchParamsCache, parseAsInteger, parseAsString } from "nuqs/server";
// Note: import from 'nuqs/server' to avoid the "use client" directive

export const searchParamsCache = createSearchParamsCache({
  // List your search param keys and associated parsers here:
  q: parseAsString.withDefault(""),
  maxResults: parseAsInteger.withDefault(10),
});

// page.tsx
import { searchParamsCache } from "./searchParams";

export default function Page({
  searchParams,
}: { searchParams: Record<string, string | string[] | undefined>; }) {
  // ⚠️ Don't forget to call `parse` here.
  // You can access type-safe values from the returned object:
  const { q: query } = searchParamsCache.parse(searchParams);
  return (
    <div>
      <h1>Search Results for {query}</h1>
      <Results />
    </div>
  );
}

function Results() {
  // Access type-safe search params in children server components:
  const maxResults = searchParamsCache.get("maxResults");
  return <span>Showing up to {maxResults} results</span>;
}
```

--------------------------------

### Parse Arrays in Svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Demonstrates parsing query parameters as arrays using parseAsArrayOf with different element parsers from nuqs-svelte. Shows both string arrays with custom separators and integer arrays. Includes UI components for adding and removing tags dynamically and displaying selected IDs.

```svelte
<script lang="ts">
  import { useQueryState, parseAsArrayOf, parseAsString, parseAsInteger } from "nuqs-svelte";

  // Array of strings with custom separator
  const tags = useQueryState(
    "tags",
    parseAsArrayOf(parseAsString, ",").withDefault([])
  );

  // Array of integers
  const ids = useQueryState(
    "ids",
    parseAsArrayOf(parseAsInteger).withDefault([])
  );

  // URL: /?tags=svelte,typescript,web&ids=1&ids=2&ids=3
  // tags.current = ["svelte", "typescript", "web"]
  // ids.current = [1, 2, 3]

  function addTag(tag: string) {
    if (tag && !tags.current.includes(tag)) {
      tags.set([...tags.current, tag]);
    }
  }

  function removeTag(tag: string) {
    tags.set(tags.current.filter(t => t !== tag));
  }

  let newTag = $state("");
</script>

<div>
  <div>
    {#each tags.current as tag}
      <span class="tag">
        {tag}
        <button onclick={() => removeTag(tag)}>×</button>
      </span>
    {/each}
  </div>

  <input bind:value={newTag} placeholder="Add tag..." />
  <button onclick={() => { addTag(newTag); newTag = ""; }}>Add</button>

  <p>Selected IDs: {ids.current.join(", ")}</p>
</div>
```

--------------------------------

### Enable Debug Logs in Browser

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Debug logs for nuqs can be enabled in the browser's developer console by setting the `debug` item in localStorage to `nuqs`. This provides insights into `useQueryState` and `useQueryStates` operations. Wildcards can be used by combining with other debug flags.

```javascript
// In your devtools:
localStorage.setItem("debug", "nuqs");
```

```javascript
// Note: unlike the `debug` package, this will not work with wildcards, but
// you can combine it: localStorage.setItem('debug', '*,nuqs')
```

--------------------------------

### Parse Query Parameters as JSON Objects with Runtime Validation (Svelte)

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Demonstrates how to use `parseAsJson` from `nuqs-svelte` to parse query parameters as JSON-encoded objects. It includes runtime validation using a custom type guard function and provides a default value.

```svelte
<script lang="ts">
  import { useQueryState, parseAsJson } from "nuqs-svelte";

  type UserFilter = {
    minAge: number;
    maxAge: number;
    roles: string[];
    verified: boolean;
  };

  // Runtime parser function for validation
  function validateUserFilter(value: unknown): UserFilter | null {
    if (
      typeof value === "object" &&
      value !== null &&
      "minAge" in value &&
      "maxAge" in value &&
      "roles" in value &&
      "verified" in value
    ) {
      return value as UserFilter;
    }
    return null;
  }

  const filter = useQueryState(
    "filter",
    parseAsJson<UserFilter>(validateUserFilter).withDefault({
      minAge: 18,
      maxAge: 65,
      roles: [],
      verified: false,
    })
  );

  // URL: /?filter=%7B%22minAge%22%3A25%2C%22maxAge%22%3A40%2C%22roles%22%3A%5B%22admin%22%5D%2C%22verified%22%3Atrue%7D
  // Decoded: {"minAge":25,"maxAge":40,"roles":["admin"],"verified":true}
</script>

<div>
  <label>
    Min Age: {filter.current.minAge}
    <input type="range" bind:value={filter.current.minAge} min="18" max="100" />
  </label>

  <label>
    Max Age: {filter.current.maxAge}
    <input type="range" bind:value={filter.current.maxAge} min="18" max="100" />
  </label>

  <label>
    <input type="checkbox" bind:checked={filter.current.verified} />
    Verified Only
  </label>

  <pre>{JSON.stringify(filter.current, null, 2)}</pre>
</div>
```

--------------------------------

### Implement Boolean Query State Parsing for UI Toggles in Svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Parses URL query parameters as boolean values using parseAsBoolean. Shows dark mode, sidebar visibility, and optional notification settings with toggle functionality and null state handling.

```svelte
<script lang="ts">
  import { useQueryState, parseAsBoolean } from "nuqs-svelte";

  const darkMode = useQueryState("dark", parseAsBoolean.withDefault(false));
  const showSidebar = useQueryState("sidebar", parseAsBoolean.withDefault(true));
  const enableNotifications = useQueryState("notify", parseAsBoolean);

  // URL: /?dark=true&sidebar=false
  // darkMode.current = true, showSidebar.current = false, enableNotifications.current = null

  function toggleDarkMode() {
    darkMode.set(d => !d, { history: "push" });
  }
</script>

<div class:dark={darkMode.current}>
  <label>
    <input type="checkbox" bind:checked={darkMode.current} />
    Dark Mode
  </label>

  <label>
    <input type="checkbox" bind:checked={showSidebar.current} />
    Show Sidebar
  </label>

  <label>
    <input type="checkbox" bind:checked={enableNotifications.current} />
    Enable Notifications {enableNotifications.current === null ? "(not set)" : ""}
  </label>

  <button onclick={toggleDarkMode}>Toggle Dark Mode</button>
</div>
```

--------------------------------

### Implement Hexadecimal Query State Parsing for Color Values in Svelte

Source: https://context7.com/rtrampox/nuqs-svelte/llms.txt

Parses URL query parameters as hexadecimal integers using parseAsHex. Converts color values between hex, RGB, and decimal formats with a color picker input and reactive transformations.

```svelte
<script lang="ts">
  import { useQueryState, parseAsHex } from "nuqs-svelte";

  const color = useQueryState("color", parseAsHex.withDefault(0xff0000));

  // URL: /?color=00ff00
  // color.current = 255 (decimal for 0xff)

  const hexString = $derived(color.current.toString(16).padStart(6, "0"));
  const rgb = $derived({
    r: (color.current >> 16) & 0xff,
    g: (color.current >> 8) & 0xff,
    b: color.current & 0xff,
  });
</script>

<div>
  <input type="color" value="#{hexString}"
    onchange={(e) => color.current = parseInt(e.currentTarget.value.slice(1), 16)} />

  <p>Hex: #{hexString}</p>
  <p>RGB: ({rgb.r}, {rgb.g}, {rgb.b})</p>
  <p>Decimal: {color.current}</p>
</div>
```

--------------------------------

### Enable Shallow Updates for Query State in Nuqs-Svelte (TypeScript)

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Opt-in to server-side refetches on state updates by setting shallow to false, defaulting to client-only updates. Only works with the SvelteKit adapter. Requires 'nuqs-svelte' and SvelteKit. Inputs are state set calls; outputs trigger network requests for data reloading. Useful for data-dependent pages.

```ts
const state = useQueryState("foo", { shallow: false });

// You can also pass the option on calls to setState:
state.set("bar", { shallow: false });
```

--------------------------------

### Set Default Values for Query State in Svelte (TypeScript)

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Shows how to handle null states by setting default values on parsers, illustrated with a counter component that avoids manual null checks. By default, absent query keys return null; using .withDefault provides a fallback value. Dependencies include 'nuqs-svelte'. Inputs depend on URL query presence; outputs are state values or defaults. Setting state to null removes the query key and reverts to the default.

```svelte
<script lang="ts">
  import { useQueryState, parseAsInteger } from "nuqs-svelte";

  const count = useQueryState("count", parseAsInteger);
</script>

<pre>count: {count.current}</pre>
<button onclick={() => count.current = 0}>Reset</button>
<!-- handling null values in setCount is annoying: -->
<button onclick={() => count.set((c) => c ?? 0 + 1)}>+</button>
<button onclick={() => count.set((c) => c ?? 0 - 1)}>-</button>
<button onclick={() => count.set(null)}>Clear</button>
```

```ts
<script lang="ts">
  import { useQueryState, parseAsInteger } from "nuqs-svelte";

  const count = useQueryState("count", parseAsInteger.withDefault(0));
  const increment = () => count.set((c) => c + 1); // c will never be null
  const decrement = () => count.set((c) => c - 1); // c will never be null
  const clearCount = () => count.set(null); // Remove query from the URL
</script>
```

--------------------------------

### Configure History Mode for Query State Updates in Nuqs-Svelte (TypeScript)

Source: https://github.com/rtrampox/nuqs-svelte/blob/main/README.md

Allows configuring history behavior for state updates, either replacing the current history entry or pushing new ones for each change, enabling back button navigation. Uses 'nuqs-svelte' library. Inputs are state change calls; outputs update browser history mode. Can override the default per update call.

```ts
// Default: replace current history with new state
useQueryState("foo", { history: "replace" });

// Append state changes to history:
useQueryState("foo", { history: "push" });
```

```ts
const query = useQueryState("q", { history: "push" });

// This overrides the hook declaration setting:
query.set(null, { history: "replace" });
```