Key Features

• Framework-agnostic core
• Full TypeScript support
• LocalStorage integration
• Complex data type support

Installation

npm install universal-url-params
# or
yarn add universal-url-params

Basic Usage

Vue 3 Composition API Example

<script setup lang="ts">
import { createVueAdapter } from 'universal-url-params';

const { useQueryParam } = createVueAdapter({
  debug: true,
  prefix: 'app_',
  debounceInterval: 200,
  localStoragePrefix: 'myapp',
  localStorageFallback: true
});

const sortParam = useQueryParam({
  name: 'sort',
  defaultValue: 'price',
  validator: (v) => ['price', 'name', 'date'].includes(v as string)
});

const timeParam = useQueryParam({
  name: 'time',
  defaultValue: 'all',
  history: { replace: true }
});
</script>

<template>
  <select v-model="sortParam.value">
    <option value="price">Price</option>
    <option value="name">Name</option>
    <option value="date">Date</option>
  </select>

  <select v-model="timeParam.value">
    <option value="all">All time</option>
    <option value="day">Last 24h</option>
    <option value="week">Last week</option>
  </select>
</template>

Advanced Features

Available Manager Options

| Option | Type | Default | Description | | ---------------------- | --------| ------- |--------------------------------------------- | | debug | boolean | false | Enable debug logging | | prefix | string | '' | Prefix for all parameters | | debounceInterval | number | 50 | URL update debounce interval (ms) | | localStoragePrefix | string | null | Prefix for localStorage keys | | localStorageFallback | boolean | false | Use localStorage if parameter missing in URL | | localStorageExpiration | number | null | Lifetime in seconds |

Parameter Options

| Option | Type | Description | | ------------ | -------------------------------------------- | --------------------------| | name | string | Parameter name (required) | | defaultValue | any | Default value | | serialize | (value: any) => string | Serialization function | | deserialize | (value: string) => any | Deserialization function | | validator | (value: any) => boolean | Validation function | | history | { replace?: boolean, scrollReset?: boolean } | History options |

Core Methods

Available

• clearLocalStorage(): void // Clear localStorage
• forceUpdateUrl(): void // Force URL update
• forceUpdateParams(): void // Force parameter sync from URL
• resetAllToDefault(): void // Reset parameters to defaults
• useQueryParam(options: QueryParamOptions): QueryParamRef // Register parameter
• useQueryParamEffect(paramNames: string[], callback: (values: any[]) => void): void
• dispose(): void // Cleanup subscriptions

Real-World Examples

Complex Filter System with Validation

<script setup lang="ts">
import { createVueAdapter } from 'universal-url-params';

const {
  useQueryParam,
  useQueryParamEffect,
  resetAllToDefault
} = createVueAdapter({
  debug: import.meta.env.DEV,
  prefix: 'filters_',
  localStoragePrefix: 'filters_v1'
});

const category = useQueryParam({
  name: 'category',
  defaultValue: 'all'
});

const priceRange = useQueryParam({
  name: 'price',
  defaultValue: [0, 1000],
  serialize: (v) => v.join('-'),
  deserialize: (v) => v.split('-').map(Number),
  validator: (v) => Array.isArray(v) && v.length === 2
});

const tags = useQueryParam({
  name: 'tags',
  defaultValue: [],
  serialize: (v) => v.join(','),
  deserialize: (v) => v.split(',').filter(Boolean)
});

useQueryParamEffect(['category'], ([newCategory]) => {
  if (newCategory !== 'all') {
    tags.value = [];
  }
});
</script>

<template>
  <button @click="resetAllToDefault">
    Reset all filters
  </button>
</template>

📄 License MIT © 2025 [Dementev V.]