Query Parameters

When building interactive applications with search, filters, and pagination, managing query parameters becomes critical. You want users to be able to bookmark filtered results, share links with specific parameters, and use the back button without losing context. Hyper gives you fine-grained control over how query parameters behave during navigation.

Understanding Query Parameter Behavior

Query parameters in URLs (?search=laravel&page=2) carry state. When navigating, you need to decide: should the new URL preserve existing parameters, replace them entirely, or merge selectively? Hyper provides explicit modifiers for each scenario.

Default Behavior: Clean Navigation

By default, navigation replaces all query parameters with those in the new URL. This is clean and predictable:

<!-- Current URL: /products?search=phone&category=electronics&page=2 -->

<a href="/products?category=computers" data-navigate="true">
    Computers
</a>

<!-- Navigates to: /products?category=computers -->
<!-- search and page parameters are removed -->

The new URL contains only the parameters explicitly specified in the href. This behavior prevents parameter pollution and gives you a clean slate for each navigation.

Merge Mode: Preserving Parameters

Use the __merge modifier when you want to preserve existing parameters and merge them with new ones:

<!-- Current URL: /products?search=laptop&category=electronics -->

<a href="/products?page=2" data-navigate__merge="true">
    Next Page
</a>

<!-- Navigates to: /products?search=laptop&category=electronics&page=2 -->
<!-- Existing parameters are preserved, page is added -->

This is perfect for pagination, where you want to keep the user's current search and filters while changing pages.

Selective Preservation with __only

The __only modifier lets you preserve specific parameters while discarding others:

<!-- Current URL: /products?search=phone&category=electronics&page=3&sort=price -->

<a href="/products?category=computers"
   data-navigate__only.search,category="true">
    Computers
</a>

<!-- Navigates to: /products?search=phone&category=computers -->
<!-- Only search and category preserved, page and sort removed -->

The __only.param1,param2 syntax lists the parameters to keep. Use comma-separated parameter names without spaces.

Selective Removal with __except

The __except modifier preserves all parameters except those specified:

<!-- Current URL: /products?search=laptop&category=electronics&page=2&sort=name -->

<a href="/products?search=tablet"
   data-navigate__except.page="true">
    Search Tablets
</a>

<!-- Navigates to: /products?search=tablet&category=electronics&sort=name -->
<!-- All parameters preserved except page (which is reset) -->

This is particularly useful for search and filter operations where you want to reset pagination but keep everything else.

Real-World Patterns

Search with Pagination Reset

When users search, you typically want to reset pagination to page 1 while updating the search term:

<div data-signals:_search="'{{ request()->search ?? '' }}'">
    <input
        type="search"
        placeholder="Search contacts"
        data-bind="_search"
        data-on:input__debounce.300ms="@navigate({search: $_search, page: 1}, 'filters', {merge: true, except:['page']})"
    />
</div>

This uses the @navigate() action (covered in Advanced) with options to merge parameters but ensure page resets to 1.

Alternatively, using the attribute syntax:

<form action="/contacts" method="GET" data-navigate__except.page="true">
    <input type="search" name="search" placeholder="Search..." />
</form>

Submitting this form preserves all query parameters except page, effectively resetting pagination.

Category Filter with Search Preservation

When applying filters, preserve the search term and other filters but reset pagination:

<!-- Current URL: /products?search=laptop&page=2 -->

<select data-bind="_category"
        data-on:change="@navigate({category: $_category, page: 1}, 'filters', {merge: true})">
    <option value="">All Categories</option>
    <option value="electronics">Electronics</option>
    <option value="books">Books</option>
</select>

<!-- When category changes to 'electronics' -->
<!-- Navigates to: /products?search=laptop&category=electronics&page=1 -->

The search term is preserved, category is updated, and page resets to 1.

Sorting with Filter Preservation

Sorting should typically preserve all current filters and search terms:

<!-- Current URL: /products?search=phone&category=electronics&page=2 -->

<a href="/products?sort=price"
   data-navigate__merge="true">
    Sort by Price
</a>

<!-- Navigates to: /products?search=phone&category=electronics&page=2&sort=price -->
<!-- All existing parameters preserved, sort added -->

Pagination with Everything Preserved

Pagination must preserve all filters, search terms, and sorting:

<div data-navigate__key.pagination__merge="true">
    {{ $products->links() }}
</div>

By wrapping Laravel's pagination links in a merged navigation context, all query parameters automatically carry forward to the next page.

Clear All Filters

When clearing filters, use clean navigation (no modifiers):

<button data-on:click="@navigate('/', 'clear')">
    Clear All Filters
</button>

<!-- OR if you want to explicitly clear specific parameters -->
<button data-on:click="@navigate({search: '', category: '', sort: '', page: 1}, 'clear')">
    Clear Filters
</button>

Combining Modifiers

You can combine navigation modifiers for precise control:

<!-- Merge parameters, but exclude page, with a custom key -->
<a href="/products?search=new-query"
   data-navigate__merge__except.page__key.filters="true">
    Search
</a>

This navigation:

1. Merges with existing parameters (__merge)
2. Excludes the page parameter (__except.page)
3. Uses the filters navigation key (__key.filters)

Implied Merge

When using __only or __except, merge mode is automatically enabled. These examples are equivalent:

<!-- Explicit merge -->
<a href="/products" data-navigate__merge__only.search="true">Link</a>

<!-- Implicit merge (same behavior) -->
<a href="/products" data-navigate__only.search="true">Link</a>

You don't need to add __merge when using __only or __except because selective preservation only makes sense with merging enabled.

Empty Parameter Values

Empty or null parameter values remove that parameter from the URL:

<!-- Current URL: /products?search=laptop&category=electronics -->

<a href="/products?search=" data-navigate__merge="true">
    Clear Search
</a>

<!-- Navigates to: /products?category=electronics -->
<!-- Empty search parameter is removed -->

This behavior keeps URLs clean and prevents meaningless empty parameters like ?search=&category=.

Working with Forms

GET forms automatically include all form fields as query parameters. Combine this with navigation modifiers for powerful filtering:

<form action="/products" method="GET" data-navigate__merge="true">
    <!-- Existing URL: /products?category=electronics -->

    <input type="search" name="search" placeholder="Search..." />
    <button type="submit">Search</button>

    <!-- Submitting with "laptop" -->
    <!-- Navigates to: /products?category=electronics&search=laptop -->
</form>

The form submission merges new parameters (from form fields) with existing URL parameters (like category).

Navigation Keys and Parameters

Navigation keys work alongside parameter modifiers. Keys determine which fragment updates, while modifiers control parameter behavior:

<a href="/products?category=computers"
   data-navigate__key.sidebar__merge="true">
    Update Sidebar
</a>

This navigation:

• Uses the sidebar navigation key (backend can detect this)
• Merges query parameters with existing ones
• Updates only the sidebar fragment (based on backend logic)

Related Topics

• Basics - Understand navigation keys and the @navigate() action
• Programmatic Navigation - Control parameters from backend controllers
• Advanced Patterns - Debounce search inputs while managing parameters
• Forms - Build search and filter interfaces that work seamlessly with navigation