vue3-use-route-query

A Vue 3 composable to get and set URL query parameters reactively with support for different data types like string, boolean, Array, number, and ....

Installation

You can install the package via npm:

npm install vue3-use-route-query

Usage

Importing the Plugin

After installation, you can use the plugin by importing useRouteQuery in your Vue components. You do not need to manually install the plugin; just import and use it.

import { useRouteQuery } from 'vue3-use-route-query';

Example: Using useRouteQuery

Here's an example of how to use the useRouteQuery composable inside a Vue component to manage URL query parameters reactively. In a Vue Component:

<template>
  <div>
    <p>Current value of "myParam": {{ myParam }}</p>
    <input v-model="myParam" />
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { useRouteQuery } from 'vue3-use-route-query';

export default defineComponent({
  setup() {
    // Use useRouteQuery to bind a query parameter to a reactive value
    const myParam = useRouteQuery('myParam', 'defaultValue', {
      type: 'string',
      navigationType: 'replace',
    });

    return { myParam };
  },
});
</script>

In this example, the myParam query parameter will be bound to the reactive variable myParam. Any changes to myParam will update the URL, and changes to the URL will automatically update the reactive variable.

Parameters

The useRouteQuery composable accepts three parameters:

1. key (string): The name of the query parameter you want to manage.
2. initialValue (TypeQuery): The initial value of the query parameter if it’s not already set in the URL.
3. config (UseRouteQueryConfig): Configuration options for the query parameter.
   • type (TypeQueryValues): The type of the query parameter. Can be one of 'boolean', 'number', 'string', 'Array', 'Array<number>', 'Array<string>', 'Array<object>'.
   • navigationType ('push' | 'replace'): The navigation type used to update the query parameter in the URL. Use 'push' to add a new entry to the history stack or 'replace' to replace the current history entry.
   • delimiter ('string' | 'undefined'): The delimiter of Arrays. default: ','

Query Types

The type field in the configuration defines how the query parameter should be processed. The following types are supported:

• boolean: Interprets the value as a boolean (true or false).

• number: Interprets the value as an number number.

• string: Interprets the value as a string.

• Array: Interprets the value as a comma-separated list of strings.

• Array<number>: Interprets the value as a comma-separated list of numbers.

• Array<string>: Interprets the value as a comma-separated list of strings.

• Array<object>: Interprets the value as a comma-separated list of JSON-encoded objects.

Example of Different Types

boolean Type

const isLoggedIn = useRouteQuery('isLoggedIn', false, {
  type: 'boolean',
  navigationType: 'replace',
});

number Type

const userId = useRouteQuery('userId', 123, {
  type: 'number',
  navigationType: 'push',
});

Array Type

const tags = useRouteQuery('tags', [], {
  type: 'Array',
  navigationType: 'replace',
  delimiter: '|'
});

Array of Objects

const filters = useRouteQuery('filters', [], {
  type: 'Array<object>',
  navigationType: 'push',
});

Handling Changes

You can also watch and modify the query parameter reactively. Any change to the queryValue will update the URL, and vice versa.

For example:

const queryValue = useRouteQuery('filters', undefined);
watch(queryValue, (newValue) => {
  console.log('Query value changed:', newValue);
});

Multi Watch

const queryValue1 = useRouteQuery('filters', undefined);
const queryValue2 = useRouteQuery('filters', undefined);
watch([queryValue1,queryValue2], () => {
  console.log('queryValue1 or queryValue2 value changed:');
});

Returns

A Ref that contains the current value of the query parameter. This value is reactive and will automatically update when the query parameter in the URL changes, and vice versa.

License

MIT License. See LICENSE for details.

Contributions

Feel free to fork and contribute to this plugin! Pull requests are welcome. Make sure to add tests for any new features or bug fixes.