<h1>Type-Safe URL Query Parameters in Vue 3 with Zod Validation: Introducing @chronicstone/vue-route-query</h1>
<h2>🚀 Introducing @chronicstone/vue-route-query</h2>
Managing URL query parameters in Vue applications often leads to repetitive boilerplate code and type safety issues. The <a href="https://github.com/chronicstone/vue-route-query" target="_blank" rel="noopener nofollow">@chronicstone/vue-route-query</a> library solves this with a powerful composable that synchronizes component state with URL parameters using Zod for validation.
<h2>✨ Key Features</h2>
<ul>
<li>🔒 Type-safe: Full TypeScript support with Zod schema validation</li>
<li>🔄 Bidirectional sync: Automatic synchronization between state and URL</li>
<li>🎯 Deep object support: Handles nested objects and arrays with serialization</li>
<li>⚡ Performance optimized: Batched updates with async processing</li>
<li>🧹 Smart cleanup: Automatically removes default values from URL</li>
<li>🔌 Vue Router integration: Seamless integration with Vue Router</li>
<li>🎨 Flexible API: Support for single values or complex objects</li>
</ul>
<h2>📦 Installation</h2>
<pre><code class="language-bash">npm install @chronicstone/vue-route-query zod vue-router
</code></pre>
<h2>🔧 Basic Usage</h2>
<h3>Single Value</h3>
<pre><code class="language-typescript">import { useRouteQuery } from &#x27;@chronicstone/vue-route-query&#x27;
import { z } from &#x27;zod&#x27;

// Simple value with automatic type inference
const activeLayout = useRouteQuery({
 key: &#x27;layout&#x27;,
 schema: z.enum([&#x27;table&#x27;, &#x27;grid&#x27;]),
 default: &#x27;table&#x27; // Won&#x27;t appear in URL when value is &#x27;table&#x27;
})

// Type: Ref&lt;&#x27;table&#x27; | &#x27;grid&#x27;&gt;
</code></pre>
<h3>Object Schema</h3>
<pre><code class="language-typescript">// Complex filtering with nested objects
const filters = useRouteQuery({
 schema: {
 search: z.string(),
 status: z.array(z.string()),
 date: z.object({
 from: z.string(),
 to: z.string()
 })
 },
 default: {
 search: &#x27;&#x27;,
 status: [],
 date: { from: &#x27;&#x27;, to: &#x27;&#x27; }
 }
})

// URL representation will be:
// ?search=test&amp;status=[&quot;pending&quot;,&quot;completed&quot;]&amp;date.from=2024-01-01&amp;date.to=2024-01-31
</code></pre>
<h3>Nullable Schema</h3>
<pre><code class="language-typescript">// Sortable table with nullable state
const sort = useRouteQuery({
 schema: {
 key: z.string(),
 dir: z.enum([&#x27;asc&#x27;, &#x27;desc&#x27;])
 },
 default: { key: &#x27;id&#x27;, dir: &#x27;asc&#x27; },
 nullable: true // Allows the entire object to be null
})

// Reset sorting
sort.value = null // Removes parameters from URL
</code></pre>
<h2>🧠 Smart Behavior</h2>
<ol>
<li>
Default Value Handling: Parameters only appear in the URL when they differ from defaults, keeping URLs clean and minimal.
</li>
<li>
Dot Notation for Objects: Nested objects use intuitive dot notation in the URL:
</li>
</ol>
<pre><code class="language-typescript">// State
{ filters: { date: { from: &#x27;2024-01-01&#x27; } } }

// URL
?filters.date.from=2024-01-01
</code></pre>
<ol start="3">
<li>Navigation Control: Choose between <code>push</code> and <code>replace</code> modes to control history behavior:</li>
</ol>
<pre><code class="language-typescript">// Creates history entries for pagination
const pagination = useRouteQuery({
 schema: { page: z.number(), limit: z.number() },
 default: { page: 1, limit: 10 },
 mode: &#x27;push&#x27; // Enable back/forward navigation
})
</code></pre>
<ol start="4">
<li>Instance Synchronization: Multiple instances with the same key stay synchronized, perfect for components that need to share state.</li>
</ol>
<h2>🔍 Real-World Example: Advanced Filtering</h2>
<pre><code class="language-typescript">const advancedFilters = useRouteQuery({
 schema: {
 searchQuery: z.string(),
 categories: z.array(z.string()),
 priceRange: z.object({
 min: z.number(),
 max: z.number()
 }),
 inStock: z.boolean(),
 sortBy: z.object({
 field: z.string(),
 direction: z.enum([&#x27;asc&#x27;, &#x27;desc&#x27;])
 }).nullable()
 },
 default: {
 searchQuery: &#x27;&#x27;,
 categories: [],
 priceRange: { min: 0, max: 1000 },
 inStock: false,
 sortBy: null
 }
})

// Apply filters programmatically
function applyFilters() {
 advancedFilters.value = {
 ...advancedFilters.value,
 categories: selectedCategories.value,
 priceRange: {
 min: minPrice.value,
 max: maxPrice.value
 }
 }
 // URL updates automatically!
}

// Reset all filters
function resetFilters() {
 advancedFilters.value = {
 searchQuery: &#x27;&#x27;,
 categories: [],
 priceRange: { min: 0, max: 1000 },
 inStock: false,
 sortBy: null
 }
 // URL parameters are removed!
}
</code></pre>
<h2>💪 Why It’s Better Than Alternatives</h2>
<ul>
<li>Zero Boilerplate: No need to manually sync state and URL</li>
<li>Type Safety: Full TypeScript inference with Zod validation</li>
<li>Clean URLs: Default values never pollute the URL</li>
<li>Performance: Smart batching prevents unnecessary router updates</li>
<li>Deep Structure Support: Handles complex nested objects with ease</li>
</ul>
Try @chronicstone/vue-route-query in your next Vue 3 project and say goodbye to URL parameter headaches!
For more details, check out the <a href="https://github.com/chronicstone/vue-route-query" target="_blank" rel="noopener nofollow">full documentation on GitHub</a>.

Hey there! Welcome to The Looop Tech - Vue.js. I’m your host IGC , your friendly neighborhood Vue.js enthusiast! Join me each week as I chat about the latest Vue.js news, share fun tips, and dive into all things Nuxt.js. It’s just me here, so if you’

Vuejs&Nuxtjs

The @chronicstone/vue-route-query library improves handling of URL query parameters in Vue 3 applications by offering type-safe synchronization using Zod validation. It supports deep object structures, automatic state synchronization, and cleans default URLs while optimizing performance and integrating seamlessly with Vue Router.