Vue Query Ref

Type-safe URL query parameter state manager for Vue 3.0+
Sync Vue refs with URL query parameters seamlessly, enhancing your app's state persistence and shareability.

🔄 Sync Vue State with URL Query Parameters Now, if you enter a value in the input field, it will be synced with the corresponding query parameter in the URL. For example, when you update the name field, the ?name= query parameter is updated in real-time. When the page is reloaded or shared, the state is restored from the query parameter, ensuring a consistent and persistent user experience. with minimal setup and no external dependencies.

📦 Features

• Reactive URL Parameters: Use URL query parameters as reactive state with minimal setup.
• Type-Safe: Supports string, number, and boolean types for query parameters.
• Easy Integration: It is a ref but syncs with URL query parameters.
• No External Dependencies: Only requires Vue 3.0+.

🚀 Installation

Install via NPM:

npm install vue-query-ref

Or with Yarn:

yarn add vue-query-ref

🌟 Usage

Basic Example

<template>
  <h1>Vue Query Sync Example</h1>
  <div>
    Name: {{ name }}
    <input
      type="text"
      v-model="name"
      placeholder="Enter your name" />
  </div>
</template>

<script setup lang="ts">
  import { useQueryParam } from 'vue-query-ref';

  // Initialize `name` with the URL query parameter `name` or default to empty string
  const name = useQueryParam('name', '');
</script>

How It Works

1. Syncs with URL:

   • When you initialize a reactive ref using useQueryParam, it synchronizes its value with a specific URL query parameter.
   • If the parameter exists in the URL, it uses that value; otherwise, it falls back to the provided default.

2. Auto-Update:

   • Changes to the ref value automatically update the URL query parameter.
   • Updating the input field in the example above modifies the ?name= query parameter in real-time.

Advanced Example

<template>
  <h1>Advanced Query Sync</h1>
  <div>
    <p>User ID: {{ userId }}</p>
    <p>Is Admin: {{ isAdmin }}</p>

    <input
      type="text"
      v-model="userId"
      placeholder="Enter user ID" />
    <label>
      <input
        type="checkbox"
        v-model="isAdmin" />
      Is Admin
    </label>
  </div>
</template>

<script setup lang="ts">
  import { useQueryParam } from 'vue-query-ref';

  // Sync with `userId` and `isAdmin` query parameters
  const userId = useQueryParam<number>('userId', 0);
  const isAdmin = useQueryParam('isAdmin', false);
</script>

URL Example:

• http://localhost:3000/?userId=123&isAdmin=true
• In this case, userId is 123 and isAdmin is true.

🛠️ API

useQueryParam

Type Signature

function useQueryParam<T extends string | number | boolean>(
  key: string,
  defaultValue: T
): Ref<T>;

Parameters:

• key (string): The query parameter key to sync with.
• defaultValue (T): The default value used when the query parameter is absent.

Returns:

• A reactive Vue ref (Ref<T>) synced with the specified query parameter.

Example:

const userId = useQueryParam<number>('userId', 0);
const username = useQueryParam<string>('username', 'Guest');
const isAdmin = useQueryParam<boolean>('isAdmin', false);

🔧 Configuration

The configuration for this library is currently a work in progress. Please stay tuned for updates. In the meantime, if you have any specific configuration needs or suggestions, feel free to contribute by opening an issue or submitting a pull request on the GitHub repository.

🛡️ TypeScript Support

The library is fully typed, ensuring seamless integration with TypeScript projects. When you use the useQueryParam composable, TypeScript infers the type based on the defaultValue provided:

const isActive = useQueryParam<boolean>('isActive', false); // Type inferred as Ref<boolean>

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Feedback & Contributions

Feedback and contributions are welcome! Feel free to open an issue or create a pull request on the GitHub repository.

👤 Author

Ebraheem Alhetari

• GitHub: hetari
• Email: [email protected]

Thank you for using Vue Query Ref! ❤️