url-query-toolkit

🔧 Lightweight utilities for managing URL query parameters and navigation in the browser.

Simple, intuitive API for working with query strings without reloading the page.

Installation

npm install url-query-toolkit

Why This Package?

Working with URL query parameters shouldn't be complicated. This toolkit provides:

✅ Simple API - Intuitive methods for common operations
✅ No page reloads - Updates URL using History API
✅ Zero dependencies - Pure JavaScript, tiny bundle size
✅ TypeScript-friendly - Full JSDoc annotations
✅ Framework agnostic - Works with vanilla JS, React, Vue, etc.

Quick Start

import { useQuery } from 'url-query-toolkit'

const query = useQuery()

// Get a parameter
const userId = query.getParam('user') // "123"

// Set a parameter
query.setParam('page', '2') // URL: ?page=2

// Get all parameters
const params = query.getAllParams() // { page: '2', user: '123' }

// Delete a parameter
query.deleteParam('user') // URL: ?page=2

// Clear everything
query.clearAllParams() // URL: (no query string)

API Reference

useQuery()

Returns an object with methods for managing URL parameters.

const query = useQuery()

getParam(key)

Get a single query parameter value.

// URL: ?name=John&age=30
const name = query.getParam('name') // "John"
const missing = query.getParam('missing') // null

Parameters:

• key (string) - Parameter name

Returns: string | null

getAllParams()

Get all query parameters as an object.

// URL: ?name=John&age=30&city=NYC
const params = query.getAllParams()
// { name: "John", age: "30", city: "NYC" }

Returns: Object<string, string>

setParam(key, value)

Set or update a query parameter. Replaces existing value.

// URL: ?page=1
query.setParam('page', '2')
// URL: ?page=2

query.setParam('sort', 'date')
// URL: ?page=2&sort=date

Parameters:

• key (string) - Parameter name
• value (string) - Parameter value

addParam(key, value)

Append a query parameter without replacing existing values.

// URL: ?tag=javascript
query.addParam('tag', 'nodejs')
// URL: ?tag=javascript&tag=nodejs

Parameters:

• key (string) - Parameter name
• value (string) - Parameter value

deleteParam(key)

Remove a query parameter from the URL.

// URL: ?name=John&age=30
query.deleteParam('age')
// URL: ?name=John

Parameters:

• key (string) - Parameter name to remove

clearAllParams()

Remove all query parameters from the URL.

// URL: ?name=John&age=30&city=NYC
query.clearAllParams()
// URL: (clean, no query string)

goToPage(url, params)

Navigate to a new page with query parameters.

query.goToPage('/search?', {
  q: 'javascript',
  sort: 'relevance',
  page: '1'
})
// Navigates to: /search?q=javascript&sort=relevance&page=1

Parameters:

• url (string) - Base URL
• params (Object) - Query parameters to append

getSlug()

Get the last segment of the URL pathname.

// URL: https://example.com/blog/my-post-title
const slug = query.getSlug() // "my-post-title"

// URL: https://example.com/products/123
const id = query.getSlug() // "123"

Returns: string

Real-World Examples

Pagination

const query = useQuery()

// Get current page
const currentPage = query.getParam('page') || '1'

// Go to next page
function nextPage() {
  const page = parseInt(currentPage) + 1
  query.setParam('page', page.toString())
}

// Go to previous page
function prevPage() {
  const page = Math.max(1, parseInt(currentPage) - 1)
  query.setParam('page', page.toString())
}

Filters and Sorting

const query = useQuery()

// Apply filters
function applyFilters(filters) {
  Object.entries(filters).forEach(([key, value]) => {
    if (value) {
      query.setParam(key, value)
    } else {
      query.deleteParam(key)
    }
  })
}

// Example usage
applyFilters({
  category: 'electronics',
  price_min: '100',
  price_max: '500',
  sort: 'price_asc'
})
// URL: ?category=electronics&price_min=100&price_max=500&sort=price_asc

Search with History

const query = useQuery()

function search(searchTerm) {
  if (searchTerm) {
    query.setParam('q', searchTerm)
  } else {
    query.deleteParam('q')
  }
}

// Restore search on page load
const savedSearch = query.getParam('q')
if (savedSearch) {
  document.getElementById('search-input').value = savedSearch
  performSearch(savedSearch)
}

Multi-Select Filters

const query = useQuery()

// Add multiple tags
function addTag(tag) {
  query.addParam('tag', tag)
}

// Get all selected tags
function getSelectedTags() {
  const params = new URLSearchParams(window.location.search)
  return params.getAll('tag') // ["javascript", "nodejs", "react"]
}

Tab Navigation

const query = useQuery()

function switchTab(tabName) {
  query.setParam('tab', tabName)
}

// Restore active tab on page load
const activeTab = query.getParam('tab') || 'overview'
showTab(activeTab)

Dynamic Product Pages

const query = useQuery()

// Get product ID from URL
const productId = query.getSlug()
// URL: /products/abc-123 → productId: "abc-123"

// Load product details
fetchProduct(productId)

// Handle variant selection
function selectVariant(color, size) {
  query.setParam('color', color)
  query.setParam('size', size)
}
// URL: /products/abc-123?color=blue&size=large

Clear Filters Button

const query = useQuery()

function clearAllFilters() {
  query.clearAllParams()
  // Optionally reload data
  loadProducts()
}

Use Cases

🔍 Search pages - Preserve search queries in URL
📄 Pagination - Share links to specific pages
🎛️ Filters & sorting - Bookmarkable filter states
🗂️ Tabs - Deep linking to specific tabs
🛒 E-commerce - Product variants, filters, sorting
📊 Dashboards - Date ranges, view modes
🎮 Game states - Level selection, difficulty

Browser Support

Works in all modern browsers that support:

• URLSearchParams
• History API

Supported:

• Chrome 51+
• Firefox 44+
• Safari 10.1+
• Edge 14+

Framework Integration

Vanilla JavaScript

import { useQuery } from 'url-query-toolkit'
const query = useQuery()
query.setParam('page', '2')

React

import { useQuery } from 'url-query-toolkit'

function SearchPage() {
  const query = useQuery()
  
  const handleSearch = (term) => {
    query.setParam('q', term)
    // Trigger re-render or refetch
  }
  
  return <input onChange={(e) => handleSearch(e.target.value)} />
}

Vue

import { useQuery } from 'url-query-toolkit'

export default {
  setup() {
    const query = useQuery()
    
    const updateFilter = (key, value) => {
      query.setParam(key, value)
    }
    
    return { updateFilter }
  }
}

TypeScript Support

Full JSDoc annotations are included. For TypeScript projects, types are inferred automatically:

import { useQuery } from 'url-query-toolkit'

const query = useQuery()
const page: string | null = query.getParam('page')

License

MIT

Contributing

Issues and pull requests are welcome on GitHub.

Made with ❤️ for better URL management