When first working with Vue, you’ll quickly notice how efficiently you can build dynamic applications, thanks in large part to one of its core features: directives. These v- prefixed attributes drive Vue’s way of syncing the DOM with your data, handling conditional rendering, binding and event listening seamlessly.

Directives define how Vue extends HTML with dynamic behaviors, forming the backbone of its reactivity. Understanding how directives observe and react to data changes is key to mastering Vue’s reactive system and creating dynamic interfaces.

In this guide, we’ll break down how Vue 3 directives work, explore the core built-in directives you’ll use every day, learn how to create them and look at some best practices to keep your templates clean and efficient. Whether you’re just starting out or brushing up on your Vue fundamentals, this post will give you a solid, practical understanding of how directives fit into Vue’s reactive world.

What Are Directives in Vue ?

At their core, directives are special HTML attributes that start with v- and apply reactive behavior to a DOM element.

Think of them as Vue’s way of giving HTML a “brain.” Instead of writing manual DOM logic, you describe what you want to happen, and Vue handles the how.

Here’s a simple example:

<p v-if="isVisible">Hello Vue!</p>

When isVisible is true, Vue renders the paragraph. When it’s false, Vue removes it from the DOM. No manual toggling, no query selectors, no manual updates. Just reactive behavior, declaratively defined.

The Anatomy of a Directive

A directive looks like this:

v-directiveName:argument.modifier="expression"

Let’s break that down:

• Directive name: E.g, v-if, v-bind, v-model
• Argument (optional): Targets something specific, like v-bind:href
• Modifier (optional): Tweaks behavior, like .prevent or .once
• Expression (optional): The data or logic it depends on

Here’s a quick example showing all parts in action:

<a v-bind:href="url" @click.prevent="trackClick">Visit</a>

Here:

• v-bind binds the href attributes to your component’s url.
• @click.prevent is shorthand for v-on:click.prevent, meaning “listen for a click and prevent the default browser behavior.”

Vue directives combine clean syntax with smart reactivity, and once you get used to them, you’ll rarely want to go back to manual DOM manipulation.

Built-in Directives You’ll Use Every Day

Vue ships with a handful of built-in directives that cover almost every common DOM scenario. Let’s go through the most important ones.

v-bind: Dynamic Attribute Binding

v-bind connects your templates to your component’s reactive data. You can bind any attribute—src, href, class, style and more to a reactive value.

<img v-bind:src="imageUrl" />

That’s the long form. The shorthand is much more common:

<img :src="imageUrl" />

You can even bind multiple attributes using an object:

<div v-bind="{ id: someId, class: someClass }"></div>

v-model: Two-Way Data Binding

v-model is one of Vue’s most magical features. It keeps your form inputs in sync with component data—automatically.

<input v-model="message" placeholder="Type something..." />
<p>{{ message }}</p>

Every time you type, the data updates. Every time the data changes, the input updates. No event listeners, no manual syncing. Just pure reactivity.

You can even use modifiers like .lazy, .number and .trim:

<input v-model.lazy="username" />

This tells Vue to update the data after the input loses focus, rather than on every keystroke.

v-if, v-else-if, v-else: Conditional Rendering

These control whether an element appears in the DOM based on a condition.

<p v-if="user">Welcome back, {{ user.name }}!</p>
<p v-else>Login to continue</p>

When the condition is false, the element is literally removed from the DOM, not just hidden. That’s great for performance when toggling expensive UI sections.

v-show: Toggle Visibility

v-show is similar to v-if, but instead of removing elements from the DOM, it simply toggles its display style:

<p v-show="isVisible">This element is still in the DOM</p>

Use v-show when you need frequent toggling and don’t want to destroy/recreate elements each time.

Quick rule of thumb:

• Use v-if when toggling rarely (it’s more expensive to re-create elements).
• Use v-show when toggling frequently (it’s faster to show/hide).

v-for: List Rendering

v-for lets you loop through arrays (or objects) to render lists.

<ul>
  <li v-for="(todo, index) in todos" :key="index">
    {{ todo.text }}
  </li>
</ul>

Always remember to include a unique :key. It helps Vue efficiently track changes and re-render only what’s necessary.

v-on: Event Handling

This one handles DOM events. It’s used to listen for and react to user actions.

<ul>
  <li v-for="(todo, index) in todos" :key="index">
    {{ todo.text }}
  </li>
</ul>

Or, with shorthand:

<button @click="count++">Clicked {{ count }} times</button>

You can chain event modifiers to control behavior:

<form @submit.prevent="submitForm">
  <input v-model="name" />
</form>

The .prevent modifier cancels the default browser action, just like event.preventDefault() would.

v-html: Rendering Raw HTML

This directive lets you render HTML content directly into the DOM.

<div v-html="rawHtml"></div>

Use it carefully, because if rawHtml contains user-generated content, it could expose you to XSS attacks. For most cases, stick with {{ }} interpolation instead.

Modifiers and Arguments in Action

Modifiers and arguments are what make directives flexible.

<input v-model.trim="username" />
<button @click.once="handleClick">Click me once</button>

• .trim cleans whitespace automatically.
• .once means the event only fires once.

These small touches make Vue’s syntax incredibly expressive and readable.

Creating Custom Directives

Sometimes, the built-ins don’t cover what you need. Maybe you need to auto-focus an input, trigger animations on scroll or integrate with a third-party library. That’s when custom directives come in.

Here’s a simple example:

app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

Usage:

<input v-focus />

Boom—instant auto-focus whenever the element mounts.

Custom directives have their own lifecycle hooks:

• created
• beforeMount
• mounted
• beforeUpdate
• updated
• beforeUnmount
• unmounted

Each hook gives you access to the element and the binding data, so you can respond to changes however you like.

Best Practices for Using Directives

Here are a few best practices for using directives:

• Keep logic inside directives simple. For complex logic, use computed properties or watchers.
• Avoid stacking too many directives on one element—it becomes harder to read.
• Use v-if and v-show appropriately based on how often the element toggles.
• Create custom directives only when a pattern truly repeats across components.

Think of directives as glue between Vue’s reactivity and the DOM, not as replacements for component logic.

Common Pitfalls to Avoid

Here are some common pitfalls to avoid when using directives:

• Using v-html with untrusted content (security risk)
• Forgetting to add a key in v-for loops
• Combining v-if and v-for on the same element (always separate them)
• Overcomplicating templates with too much logic inside directives.

Directives are powerful, but they’re meant to stay declarative. The heavy lifting should still live in your component logic.

Putting It All Together—A Mini Example

It’s one thing to read about directives, but seeing them in action ties everything together.

Below is a small Vue Todo app that shows how multiple directives work in harmony—from conditional rendering to event handling and even custom directives.

You can try this example live in CodeSandbox or StackBlitz, or drop it into your local Vue project to see it run.

You can try this example live in CodeSandbox or StackBlitz, or drop it into your local Vue project to see it run.

<template>
  <div class="todo-app">
    <h2>My Todo List</h2>

    <!-- Input field with v-model and a custom v-focus directive -->
    <input
      v-model.trim="newTodo"
      v-focus
      placeholder="Add a new todo"
      @keyup.enter="addTodo"
    />

    <!-- Conditional rendering using v-if / v-else -->
    <p v-if="todos.length === 0">No todos yet. Add one above </p>
    <ul v-else>
      <!-- Loop through todos using v-for -->
      <li
        v-for="(todo, index) in todos"
        :key="index"
        :class="{ done: todo.done }"
      >
        <!-- Toggling state with v-on -->
        <span @click="toggleDone(todo)">
          {{ todo.text }}
        </span>

        <!-- Delete button -->
        <button @click.prevent="removeTodo(index)">x</button>
      </li>
    </ul>

    <!-- Show summary using v-show -->
    <p v-show="todos.length > 0">
      {{ remaining }} remaining
    </p>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'

// Custom directive: auto-focus input on mount
const vFocus = {
  mounted(el) {
    el.focus()
  },
}

const todos = ref([])
const newTodo = ref('')

const addTodo = () => {
  if (newTodo.value.trim()) {
    todos.value.push({ text: newTodo.value, done: false })
    newTodo.value = ''
  }
}

const removeTodo = (index) => {
  todos.value.splice(index, 1)
}

const toggleDone = (todo) => {
  todo.done = !todo.done
}

const remaining = computed(() => todos.value.filter((t) => !t.done).length)
</script>

<style scoped>
.todo-app {
  max-width: 400px;
  margin: 2rem auto;
  text-align: left;
  font-family: system-ui, sans-serif;
}
.done {
  text-decoration: line-through;
  color: gray;
}
button {
  margin-left: 0.5rem;
  background: none;
  border: none;
  color: crimson;
  cursor: pointer;
}
button:hover {
  color: red;
}
</style>

What’s Happening Here

This small example brings together almost every directive we’ve talked about:

• v-model keeps the input field and data in sync.
• v-focus (a custom directive) automatically focuses the input when mounted.
• v-if / v-else handle conditional rendering for the “todo yet” message.
• v-for loops through the list of todos and binds a unique :key.
• @click (shorthand for v-on:click) handles toggling and removing items.
• v-show conditionally shows the “remaining” count without removing it from the DOM.

This little component shows how directives make your templates reactive, declarative and readable. No manual DOM code, no boilerplate event logic, just Vue doing what it does best.

Wrapping It Up

Directives are one of those features that make Vue feel effortless once you understand them. Instead of micromanaging the DOM, you describe what you want to happen, and Vue handles the rest. From dynamic bindings to conditional rendering and custom behaviors, a directive is the bridge between your data and your UI.

If you’ve followed along up to this point, you’ve already touched nearly every directive you’ll use in day-to-day Vue work, and even built your first custom one. That’s a solid step toward thinking declaratively and writing cleaner, more maintainable Vue components.

In our previous post, we went a level deeper and looked at Vue’s lifecycle hooks, the what happens inside a component. Understanding the lifecycle will help you know exactly when to run logic, register listeners or clean things up as your components mount and unmount.

​If you’ve been enjoying this series, stick around, we’re just getting started. Follow along for more Vue Basics guides where we’ll continue breaking down the framework piece by piece, in a way that feels practical and developer-friendly.

If you’ve ever wondered why Vue feels so effortless, why your UI just knows when to update, it all boils down to one thing: reactivity. Vue’s reactivity system is the magic behind its simplicity. It turns plain JavaScript data into a living, self-updating state that automatically keeps your UI in sync with your logic.

In this guide, we’ll go beyond “it just works” and unpack how Vue 3’s reactivity actually functions, what makes it so intuitive, what’s happening under the hood and how you can use it effectively in your own components.

What Reactivity Means (and Why It’s Awesome)

Before Vue (and frameworks like it), updating the UI meant manually syncing your data and the DOM. Change a value? You’d have to find the element, update the text and keep track of what’s what.

Vue’s reactivity flips that process on its head. Now, your data becomes the single source of truth, and Vue automatically keeps your UI in sync with it. Change the data, and the DOM reacts. That’s the essence of reactivity.

Here’s a quick taste:

import { reactive } from 'vue'
const state = reactive({ count: 0 })

function increment() {
  state.count++
  // The DOM updates automatically
}

For example, after you make state reactive, you no longer need to manually update the DOM; Vue handles this using dependency tracking.

Behind the scenes, Vue 3’s reactivity system is powered by modern JavaScript Proxies. When you make an object reactive, Vue wraps it in a proxy that “intercepts” reads and writes:

• When you read a property, Vue tracks that dependency.
• When you change it, Vue knows exactly which parts of the DOM depend on it and updates them efficiently.
  Think of it as a super-smart observer pattern baked directly into your data layer.

The Core APIs You’ll Use

Let’s walk through the main tools Vue provides to make your data reactive and useful.

reactive(): Make Objects Reactive

Use reactive() when working with objects, arrays, or anything with multiple properties.

import { reactive } from 'vue'

const user = reactive({
  name: 'David',
  age: 25
})

user.age++ // reactivity in action

Every nested property inside reactive() is tracked automatically, giving you deep reactivity out of the box.

ref(): Reactivity for Primitives

Objects work great with reactive, but what about primitives like numbers, strings or booleans?

That’s where ref() comes in:

import { ref } from 'vue'

const count = ref(0)

function increment() {
  count.value++
}

Notice value? That’s how you access the actual value inside a ref. Vue adds this layer because primitive values (like numbers or strings) can’t be wrapped in proxies directly.

The cool part: inside templates, Vue automatically unwraps refs, so you can use {{ count }} instead of{{ count.value }}` in your template.

Rule of thumb:

• Use ref() for single values (primitives).
• Use reactive for objects and collections.

computed(): Derived, Read-Only State

Sometimes, your data depends on other data. Instead of manually updating values, let Vue handle it with computed().

import { ref, computed } from 'vue'

const price = ref(100)
const quantity = ref(2)

const total = computed(() => price.value * quantity.value)

computed properties are cached and only rerun when their dependencies change—perfect for anything derived from existing state.

watch() and watchEffect(): Responding to Changes

watch() is your go-to for running side effects when reactive data changes—for example, saving data to localStorage or triggering an API call.

import { ref, watch } from 'vue'

const username = ref('')

watch(username, (newValue) => {
  localStorage.setItem('username', newValue)
})

watchEffect works similarly but is even more automatic. It immediately runs and tracks dependencies on its own:

import { ref, watchEffect } from 'vue'

const count = ref(0)

watchEffect(() => {
  console.log(`Count is now ${count.value}`)
})

If you’re not sure which one to use, start with watchEffect(). It’s simpler for quick reactions to state.

How Vue’s Reactivity Works Under the Hood

Here’s a high-level mental model of how Vue’s reactivity works:

1. You access a reactive property → Vue tracks it.
2. You change that property → Vue triggers updates.
3. Vue efficiently re-renders only what depends on it.

Want to peek behind the curtain? Here’s a simplified reactivity system you can try yourself:

let value
const subscribers = new Set()

function effect(fn) {
  subscribers.add(fn)
  fn()
}

function set(newVal) {
  value = newVal
  subscribers.forEach(fn => fn())
}

// Usage
effect(() => console.log('Value is', value))
set(1) // logs "Value is 1"
set(2) // logs "Value is 2"

That’s basically what Vue does, just much more optimized and feature-rich.

Reactivity in the Composition API
The Composition API is built entirely on top of reactivity. Inside setup(), you can freely mix ref(), reactive(), computed() and watch() to manage state and logic cleanly:

<script setup>
import { reactive, computed } from 'vue'

const cart = reactive({
  items: [],
})

const total = computed(() =>
  cart.items.reduce((sum, item) => sum + item.price, 0)
)

function addItem(item) {
  cart.items.push(item)
}
</script>

Everything inside setup() stays reactive and automatically updates your template whenever your state changes .

Practical Example—A Reactive Todo List

Here is everything in action:

<script setup>
import { reactive, computed, watch } from 'vue'

const todos = reactive({
  list: [],
  newTodo: ''
})

const total = computed(() => todos.list.length)

function addTodo() {
  if (!todos.newTodo) return
  todos.list.push(todos.newTodo)
  todos.newTodo = ''
}

watch(
  () => todos.list,
  (newList) => localStorage.setItem('todos', JSON.stringify(newList)),
  { deep: true }
)
</script>

<template>
  <div>
    <input v-model="todos.newTodo" placeholder="Add a todo" />
    <button @click="addTodo">Add</button>
    <p>Total: {{ total }}</p>

    <ul>
      <li v-for="todo in todos.list" :key="todo">{{ todo }}</li>
    </ul>
  </div>
</template>

In this example:

• reactive() manages our state object
• computed() handles derived totals
• And watch() persists the data

Everything is tied together by Vue’s reactivity system. Everything stays perfectly in sync without a single manual DOM update.

Gotchas and Edge Cases

Even though Vue’s reactivity feels seamless, there are a few quirks worth remembering:

• Destructuring breaks reactivity:

const { count } = reactive({ count: 0 })
count++ // ❌ not reactive anymore

Always access properties directly from the reactive object.

• Ref vs. reactive confusion: You can’t use .value on a reactive object, only on a ref.
• Shallow reactivity: If you only need top-level tracking, shallowReactive() or shallowRef() might be better for performance-heavy objects.
• Reassigning reactive objects: Reassigning a whole reactive object breaks its reference. Mutate its properties instead.

Wrapping Up

Understanding Vue’s reactivity is like unlocking the framework’s secret language. Once you understand how data flows and updates behind the scenes, everything from state management to the Composition API starts to click.

As an add-on, take a look at these best practices for working with reactivity:

• Prefer computed over watch for derived state.
• Keep watchers side-effect-free.
• Avoid unnecessary .value access—templates handle that for you.
• Be cautious when mixing reactive and non-reactive data.
• Don’t overuse reactivity—keep it simple and purposeful.

In addition, here are tips for debugging reactivity when things don’t seem to update as expected:

• Use isReactive() or isRef() to check what’s reactive.
• Use toRaw() if you need the original, unwrapped object (for logging or external libraries).
• Vue DevTools can visualize your reactivity graph—extremely helpful for debugging complex state.

If you’ve enjoyed this deep dive, stick around—this article in this Vue Basics series explores how Vue’s lifecycle hooks tie into reactive state and when to tap into them for precise control over your components.

State is one of the first core concepts you’ll encounter when building anything interactive with Vue. Whether it’s the text in a form, the items in a cart or the logged-in user’s profile, managing that state properly is essential for keeping your app stable, reactive and easy to scale.

Vue 3 introduced the Composition API along with a revamped reactivity system, giving developers more powerful and flexible ways to manage state than ever before. In this guide, we’ll explore how Vue 3 handles state—starting from local state with ref and reactive, to sharing data with props and provide/inject, and finally leveling up to Pinia, Vue’s official state management library. By the end, you’ll have a clear roadmap for choosing the right tool for your app’s needs.

Understanding the Concept of State Management in Vue

State is at the heart of every interactive Vue app. It’s what makes your UI dynamic—update the state, and Vue automatically reflects those changes in the DOM.

Broadly, there are two types of state:

• Local state: Exists inside a single component (e.g., a count variable in a counter component)
• Global state: Shared across multiple components or sections of your app (e.g., user authentication status)

By default, every Vue component maintains its own reactive state, which we often refer to as local state. Let’s start here before exploring how to share state across components and eventually manage it globally with Pinia.

Local State with ref and reactive

To manage local reactive state, the Vue 3 Composition API offers two main tools: ref and reactive. If you’re new to Vue, deciding which to use can be confusing—so let’s break it down, building on our understanding of local state.

Using ref

Use ref when working with primitive values (numbers, strings, booleans).

<script setup>
import { ref } from 'vue'

//state
const count = ref(0)

//actions
function increment() {
  count.value++
}
</script>

<!-- view -->
<template>
  <button @click="increment">Count is: {{ count }}</button>
</template>

Here,count is wrapped in a ref, and its value is accessed via .value.

Using reactive

Use reactive when working with objects or arrays.

<script setup>
import { reactive } from 'vue'

const user = reactive({
  name: ' ',
  age: 25
})
</script>

<template>
   <input v-model="user.name" placeholder="Enter your name" />
  <p>{{ user.name }} is {{ user.age }} years old.</p>
</template>

Behind the scenes, Vue wraps the object in a Proxy, so it can automatically track changes and update the DOM.

Local state is the simplest example of Vue’s one-way data flow: the state drives the UI. But once multiple components need to share the same piece of state, managing it locally becomes difficult, and that’s when we move beyond local state.

Sharing State Between Components

Local state works fine for a single component, but what if multiple components need the same data? Vue gives us several ways to share state: props/emits and provide/inject.

Props and Emits

Props let a parent pass state down, while emits let children send events up.

Let’s take a look at this simple demo below:

Parent Component

You can pass data from parent to child via props.

<!-- Parent.vue -->
<template>
  <Child :count="count" @increment="count++" />
</template>

<script setup>
import { ref } from 'vue'
import Child from './Child.vue'

const count = ref(0)
</script>

Child Component

When the child needs to update the parent’s state, it can emit an event.

<!-- Child.vue -->
<template>
  <button @click="$emit('increment')">Clicked</button>
</template>

<script setup>
defineProps(['count'])
defineEmits(['increment'])
</script>

This approach works well for small apps, but if you have deeply nested components, passing props and emits around quickly becomes messy, leading to another problem known as prop drilling. To avoid this, Vue provides an alternative option: provide/inject.

Provide/inject: Avoiding Prop Drilling

The provide/inject API in Vue makes it easy for a parent component to share data with its children, no matter how deeply nested they are, without having to pass props down through every intermediate layer.

Let’s take a look at this simple code demo below:

Parent Component

<!-- ParentComponent.vue -->
<script setup>
import { ref, provide } from 'vue'
import ChildComponent from './ChildComponent.vue'

   const count = ref(0)
   provide('count', count)

   const increment = () => {
      count.value++
  }
</script>

<template>
  <div>
    <h2>Parent Count: {{ count }}</h2>
    <button @click="increment">Increment</button>
    <!-- Pass down without props -->
    <ChildComponent />
  </div>
</template>

The provide() function is used in a parent component to make data available to its descendants. It takes two arguments: an injection key and a value. The key can be either a string or a symbol, and descendant components will use that key to access the corresponding value through inject(). A single component isn’t limited to one call; you can call provide() multiple times with different keys to share different values.

The second argument of provide() is the data you want to share, which can be of any type—primitives, objects, functions or even reactive state like ref or reactive. When you provide a reactive value, Vue doesn’t pass a copy; it establishes a live connection, allowing descendant components that inject() it to automatically stay in sync with the provider.

Child Component

<!-- ChildComponent.vue -->
<script setup>
import GrandChildComponent from './GrandChildComponent.vue'
</script>
<template>
  <div>
    <h3>I am the Child</h3>
    <!-- Notice: no prop passing -->
    <GrandChildComponent />
  </div>
</template>

To inject data provided by an ancestor component, make use of the inject() function in the GrandChildComponent.vue:

<!-- GrandChildComponent.vue -->
<script setup>
import { inject } from 'vue'
const count = inject('count')
</script>
<template>
  <div>
    <p>Grandchild sees count: {{ count }}</p>
  </div>
</template>

In the code demo above, the ParentComponent provides the reactive count, so the ChildComponent doesn’t need to do anything—it just passes the slot/children down. Then the GrandChildComponent can directly inject count and stay reactive to parent updates

This is a basic demo of how to use the provide/inject pattern; however, if you want to learn more, this post covers it in great detail: Vue Basics: Exploring Vue’s Provide/Inject Pattern.

The provide/inject pattern is perfect for avoiding prop drilling in medium-sized apps. However, as your app grows, managing dependencies this way can get complicated. For larger and complex apps, we need a dedicated state management solution that is more structured and scalable, which is where libraries like Pinia come in.

State at Scale with Pinia

As your app grows, manually managing state across multiple components quickly turns into a headache. The patterns we covered earlier work fine for smaller projects, but once you’re building a large-scale production application, there are many things to consider:

• Hot Module Replacement
• Stronger conventions for team collaboration
• Integrating with the Vue DevTools, including timeline, in-component inspection and time-travel debugging
• Server-side rendering support

You need a central store, a single source of truth that multiple components can read and write to, and that is where Pinia comes in.

Pinia is the official state management library for Vue 3 and the successor to Vuex. It’s designed to handle all the scenarios we listed above. It’s much simpler, more intuitive and built to work seamlessly with the Composition API.

Before we dive into the code demo, let’s make sure we’re clear on the fundamentals. At its core, state management is about where your data lives, how you read it and how to update it. Pinia formalizes this with four concepts:

• State: This is your actual reactive data. Think of it as the source of truth for your app. For example, a user’s profile details, the item in a cart or whether a modal is open.
• Store: The centralized container that holds your state. Instead of scattering data across multiple components, the store centralizes it, so any components can access and update it without messy prop drilling.
• Getters: These act like computed properties for your store. They let you derive or transform state values (for example, calculating the cost of items in a cart) without duplication logic in multiple places.
• Actions: Functions that update your state. They’re like methods in a Vue component, and they’re where you keep the logic for making changes, whether it’s incrementing a counter, adding an item to a list or fetching data from an API.

Think of it this way:

• State is what you have
• Getters are how you view it
• Actions define how it changes
• The store is where it all lives

So let’s demonstrate how to integrate Pinia with our counter demo app.

Setting Up Pinia

Setting up Pinia for a Vue 3 single-page application is straightforward. If you’re creating a new project from scratch using the Vue CLI or create-vue, the setup wizard will even ask if you want to use Pinia as your state management of choice.

To set up Pinia manually in a new project—or add it to an existing app—follow these steps:

First, install the Pinia package using either npm or yarn:

npm install pinia

# or

yarn install pinia

To register Pinia in your app, open your entry file (usually main.js or main.ts) where the app is mounted, and call app.use(pinia) on your Vue application instance:

main.js

// main.js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
const app = createApp(App)

app.use(pinia)
app.mount('#app')

Now we can move to creating the store for the counter demo app.

Creating a Store

Here’s a simple counter store that demonstrates all four concepts. To create a store, start by making a new file that holds its code. A good practice is to place these files inside a dedicated stores folder to keep your project organized.

CounterStore.js

export const useCounterStore = defineStore('counter',  {

----

})

To create a store, we use Pinia’s defineStore method. It takes two main arguments: the first is the store’s id, which must be unique across your application. You can name it anything you like, but for this example, counter is the most fitting since that’s exactly what our store manages.

The second argument is an object that defines the store’s options. Let’s break down what we can include inside it:

State

The first option to define in a store is state. If you’ve worked with Vue’s Options API, this will feel familiar. It’s simply a function that returns an object holding all the reactive data your store should manage. For our counter app demo, we’ll add count property to the state:

export const useCounterStore = defineStore('counter',  {
// State — the reactive shared data
  state: () => ({
     count: 0,
})

Then we can easily import this store in our CounterButton.vue component and make use of the count states.

CounterButton.vue

<script setup>
import { useCounterStore } from '../stores/CounterStore.js’
const counter = useCounterStore()
</script>
<template>
  <div>
  <button >
    Clicked {{ counter.count }} times
 </button>
 
  </div>
</template>

In the above code example, we imported the useCounterStore and then called the method. This will return a copy of the counter store that we created earlier. The state in this store is global, meaning any updates made to it will automatically be reflected across all components that use the store.

Getters

Just like Vue’s computed properties, Pinia stores allow us to define getters. A getter is essentially a computed value that’s derived from the store’s state. They’re useful when you want to transform, filter or calculate something based on the existing state without duplicating logic across components. For example, we can calculate the multiplication of the current state using the getter method:

Update your CounterStore.js with the following code:

export const useCounterStore = defineStore('counter',  {

// State — the reactive shared data
  state: () => ({
     count: 0,
})

// Getters — derived state
  getters: {
    doubleCount: (state) => state.count * 2
  },

})

That is it. Now we now have a doubleCount property that we can use across any component.

Create a CounterDispay.vue component to use the doubleCount property to display message to the user.

<script setup>
import { useCounterStore } from '../stores/CounterStore.js'
const counter = useCounterStore()
</script>

<template>
  <div>
    <p>Current Count: {{ counter.count }}</p>
    <p>Double Count: {{ counter.doubleCount }}</p>
  </div>
</template>

Getters are synchronous by design. If you need to perform asynchronous work (like fetching data), use an action instead.

Actions

The last option we can define in our store is actions. Think of actions as the store’s version of component methods—they encapsulate the logic for changing state or performing tasks. Unlike getters, which are only for deriving and returning data, actions are designed to update state and handle side effects.

One major advantage of actions is that they can be asynchronous, unlike getters. This makes them ideal for tasks such as fetching data from an API, handling form submissions or performing any operation that takes time before committing the result back to the store. For example, this is a good location to create a logic to increment the state count or fetch the initial count data from your API.

Open our CounterStore.js and update with the following code:

export const useCounterStore = defineStore('counter',  {

// State — the reactive shared data
  state: () => ({
     count: 0,
})

// Getters — derived state
  getters: {
    doubleCount: (state) => state.count * 2
  },

// Actions — logic to update state
actions: {
    increment() {
      this.count++
    },

    async fetchInitialCount() {
      const res = await fetch('/api/count')
      const data = await res.json()
      this.count = data.value
    }
  }

  }

})

Now inside a CounterButton.vue component, you can call the action instead of directly mutating the state:

<script setup>
import { useCounterStore } from '../stores/CounterStore.js’
const counter = useCounterStore()
</script>

<template>
  <button @click="counter.increment">Increment</button>
  <button @click="counter.fetchInitialCount">Load Initial Count</button>
  <p>Count is: {{ counter.count }}</p>
</template>

From the code modification above, the increment() is a simple action that directly modifies the store’s state, while the fetchInitialCount() demonstrates that action also handles asynchronous tasks, like timers or APIs. And since Pinia stores are reactive, once an action updates the state, all components using that store will instantly reflect the new value.

Wrapping Up

State management in Vue doesn’t have to be overwhelming. Start small with ref and reactive for local state. When components need to communicate, props and emits are a natural fit. As your app grows, provide/inject helps reduce prop drilling and keeps things organized.

But when your application requires a state that’s shared and consistent across many components, Pinia stands out. It provides a centralized, scalable store that serves as the single source of truth for your app.

Knowing when to use each approach is the real key. You don’t need Pinia from day one, but as your project becomes more complex, you’ll appreciate its structure and reliability. With these options in hand, you can manage state confidently—whether you’re building a small widget or a full-scale production app.

If you want to go beyond the basics, the official Pinia documentation is the best next step. It dives into plugins, advanced patterns, devtools integration and more—all explained in a clear and practical way.

If you’ve been working with Vue or are new to it, understanding how your Vue components are created, updated and eventually destroyed is very important, and one of the most powerful concepts you’ll encounter is lifecycle hooks. These hooks give precise control over what your component does at each phase of its life, from setup and rendering to updates and cleanup.

Whether you’re spinning up a simple component or architecting a complex application, getting a handle on lifecycle hooks will save you from hours of confusion down the road. In this guide, we’ll walk through each stage of the Vue 3 component lifecycle using the Composition API, the modern and scalable approach to building Vue apps.

Prerequisites

• To follow along, you’ll need Node.js installed on your machine. If you’re new to Vue, feel free to check out this setup guide for getting a fresh Vue project up and running.
• Alternatively, you can fork this Vue 3 CodeSandbox boilerplate, which I’ll be using throughout the tutorial.
• A basic knowledge of Vue.js.

Cool? Let’s dive in.

What Are Vue.js Lifecycle Hooks?

When a Vue component instance is created, it follows a series of initialization steps: setting up data observation, compiling the template, mounting to the DOM, updating the DOM as data changes and unmounting the DOM. During this process, Vue invokes lifecycle hooks, allowing developers to run custom code at specific stages.

Lifecycle hooks are crucial in Vue.js because they offer insight into the framework’s inner workings. They enable you to perform actions during different stages of the Vue component lifecycle. These stages include creation, mounting, updating and unmounting.

Understanding these stages and the hooks associated with each is key to grasping the Vue reactivity system and managing component behavior effectively.

The Vue Composition API

Vue components can be authored in two different API styles: Options API and the Composition API introduced in Vue 3.

The Composition API is a set of APIs that allows us to author Vue components using imported functions instead of declaring options. One of the primary advantages of Composition API is that it enables efficient logic reuse in the form of composable functions. It solves the drawbacks of mixins, the primary logic reuse mechanism of the Options API. It helps developers organize complex logic and separate concerns into modular, testable units, making their codebases easier to maintain and scale.

Vue 3 maintains backward compatibility with Vue 2, so both versions share similar lifecycle hooks. However, when you use the Composition API, you access these hooks a bit differently. We will look at the lifecycle hooks using the Composition API style.

Moving forward, we will categorize all the various types of lifecycle hooks according to their functionality: creation, mounting, updating and unmounting hooks. We will explore each hook and showcase actions that are allowed at each stage of the instance lifecycle.

Below is the diagram for the instance lifecycle hook:

Reference: https://vuejs.org/guide/essentials/lifecycle.html

Open your Vue starter application or use the codesandbox boilerplate to follow along. Open the HelloWorld.vue file in your component folder and edit the code with this below:

<template>
  <h1>{{ msg }}</h1>

  <div class="card">
     <button type="button" @click="increment">Count is {{ count }}</button>
 </div>
</template>

<script >
// import the lifecycle hooks from vue
import { ref, onBeforeMount, onMounted, onBeforeUpdate, onUpdated, onBeforeUnmount, onUnmounted } from "vue";

export default {
 setup() {
   // use ref to create a reactive state
   const msg = ref("Hello Vue 3");
   const count = ref(0);

   // define a method to increment the counter
   const increment = () => {
     count.value++;
   };

   // return the state and methods to the template
   return {
     msg,
     count,
     increment
   };
 }
};
</script>

<style scoped>
.read-the-docs {
 color: #888;
}
</style>

This code above is a counter component that updates the state of the count when the button is clicked. We will use only the script section to explain the subsequent part of this article. Also, in Composition API, you need to import lifecycle hooks in your project before you can use them, just as shown in the code snippet above.

Creation Phase (setup() Hook)

The creation phase is the initial stage of a Vue component lifecycle. This phase is critical because it lays the groundwork for everything that follows in the component’s existence. During this phase, Vue begins constructing the component instance before it is added to the DOM. At this point, Vue sets up reactivity by observing the component’s reactive state. This phase includes the beforeCreate and created lifecycle hooks in the Options API, while in the Composition API, this is where the setup() hook is called.

The setup() Hook

The setup() hook serves as the entry point for Composition API usage in your component. It is the first lifecycle hook called in Vue, triggered immediately after the application instance is initialized. In the Composition API, the setup() hook replaces the beforeCreate() and created() hooks previously used in the Options API.

The setup() hook is ideal for tasks that should run once the component is fully set up, such as configuring event listeners or fetching data from an API.

Add the following code below within your setup hook:

alert("The creation phase has been initialized")

The code above will display this:

You’ll notice the alert statement runs before the component is loaded. This occurs because the function is executed before the Vue engine creates and mounts the app component.

Mounting Phase (Mounting Hooks)

The mounting phase marks the moment your Vue component renders for the first time and is inserted into the DOM, making it visible in the browser. This phase begins after the component has been fully created and reactive systems have been initialized (in the creation phase).

The associated lifecycle hooks in this phase give you precise control over what to do before and after the initial render, making them powerful tools for managing the component’s dynamic behavior. Keep in mind that these hooks don’t run during server-side rendering since the server doesn’t have access to a real DOM.

In the Options API, the mounting phase includes two hooks: beforeMount() and mounted(). The equivalent hooks in Composition API are onBeforeMount() and onMounted().

onBeforeMount()

After Vue runs the setup() hook, it immediately calls the onBeforeMount() lifecycle hook. By this time, Vue has already initialized the component’s reactive state, but it hasn’t created the DOM yet. Since the component is about to render for the first time, you still can’t access or manipulate the DOM—the element property (which points to the root DOM element) isn’t available yet.

It’s an ideal place for setup logic that needs to run before the initial render but doesn’t depend on the DOM being available:

 onBeforeMount(() => {
   alert('onBeforeMount has been initialized')
 });

onMounted()

After Vue calls the onBeforeMount() hook and prepares the component for rendering, it proceeds to mount the component by rendering its template and inserting the resulting DOM element into the page. Once Vue completes this process, it immediately calls the onMounted() lifecycle hook.

At this point, the component is fully available in the DOM. Now you can safely perform operations that depend on DOM access, such as interacting with DOM elements, setting up event listeners or making API calls that require the DOM to be available.

In the Composition API, onMounted() is registered inside the setup() function and is called once after the first render:

 onMounted(() => {
    // You can now access the DOM or perform other side effects
    console.log('Component is mounted and the DOM is now accessible.');
 });

Unlike onBeforeMount(), which runs before the DOM is ready, onMounted() runs after the DOM is fully constructed, making it an ideal hook for any logic that needs the component to be fully rendered and interactive in the DOM.

Updating Phase (Updating Hooks)

The updating phase is that phase of the Vue lifecycle that is triggered whenever the component reactive data changes. Whenever a reactive value changes, Vue automatically rerenders the affected parts of the DOM using its virtual DOM diffing algorithm. These two hooks below let you tap into the update process before and after a DOM rerender occurs:

onBeforeUpdate()

After the mounting hooks, onBeforeUpdate() is called right before a component is about to update its DOM tree due to a reactive state change. It gives you access to interact with or inspect the DOM state before Vue updates the DOM based on the new reactive values.

It’s helpful when you want to capture the DOM state before changes, debug rendering issues by comparing old vs new state, perform cleanup or prep work before the DOM is updated etc. It’s the equivalent of the beforeMount() hook in the Options API.

Here is the basic usage in our counter app:

 onBeforeUpdate(() => {
     // DOM is still in its previous state
     alert('onBeforeUpdate has been called');
 });

 onMounted(() => {
    console.log('onMounted hook');
    console.log(count.value);
 });

onUpdated()

In the Composition API, the onUpdated() hook is called after the component has rerendered due to a change in its reactive state. It gives you access to the updated DOM, making it ideal for performing post-render DOM-dependent operations. It’s advisable not to mutate components in the updated hook, as it will likely lead to an infinite update loop.

It pairs well with onBeforeUpdate() as it allows you to access the old DOM and the new DOM. For instance, this pairing is powerful for comparing before-and-after states or restoring scroll and focus behavior. It’s the equivalent of the updated() hook in the Options API.

Pair it with the previous demo in the onBeforeUpdate() example:

  onBeforeUpdate(() => {
     // DOM is still in its previous state
     alert('onBeforeUpdate hook');
     console.log('About to update the current value:', count.value);
  });

  onUpdated(() => {
     console.log("onUpdated hook");
     console.log(count.value);
     // You can now interact with updated DOM elements here
  });

Click on the counter button and look into the console to see the flow of the lifecycle hooks:

Unmounting Phase (Unmounting Hooks)

The unmounting phase marks the final stage in a Vue component’s lifecycle. It begins when Vue decides to remove the component from the DOM. During this phase, Vue actively cleans up the component to free memory, prevent memory leaks, and stop any reactive effects or event listeners from running after the component is no longer needed.

In the Options API, this phase includes two hooks: beforeUnmount() and unmounted(). In the Composition API, you’ll use onBeforeUnmount() and onUnmounted() instead. The unmounting phase in Vue 3 focuses entirely on cleaning up side effects before Vue removes the component from the DOM.

onBeforeUnmount()

In Vue 3’s Composition API, Vue calls the onBeforeUnmount() hook right before it unmounts and removes the component from the DOM. This hook gives you a final opportunity to run cleanup logic while the component instance and its DOM elements are still fully accessible and functional.

 onBeforeUnmount(() => {
    console.log('Component is about to be unmounted.');
 });

This hook is ideal for removing event listeners, cancelling timers, deleting variables and destroying third-party tools especially if they depend on the current DOM or component state.

onUnmounted()

The onUnmounted() hook is called after a component has been fully removed from the DOM and its reactive effects have been cleaned up. Think of onUnmounted() as the last opportunity to clean up any side effects that do not require access to the DOM or to the component’s internal state (since the DOM and reactive context are now gone or inactive). It is suitable for cleaning up global side effects that could cause memory leaks or unexpected behavior if left running after the component is gone.

onUnmounted(() => {
    console.log('Component has been unmounted.');
});

It is your final cleanup hook perfect for shutting down anything that continues running outside the component’s DOM.

Additional Life Cycle Hooks

Vue 3 introduced several additional lifecycle hooks beyond those in Vue 2, particularly in the Composition API to support more advanced use cases, improve flexibility and enhance support for features like Suspense, teleport and asynchronous setup.

Below is a breakdown of these additional lifecycle hooks and how you can use them:

onRenderTracked() and onRenderTriggered()

These hooks help you debug your component’s reactivity behavior during development. Vue calls onRenderTracked() during development when the component’s render effect tracks a reactive dependency. This hook helps you debug reactivity by showing which reactive properties the component tracks while rendering.

The onRenderTriggered() hook runs during development when a reactive dependency triggers a rerender. It helps debug performance issues and shows you which reactive value caused the component to rerender. Both onRenderTracked() and onRenderTriggered() are only active in development mode, not in production builds. They are equivalent to the renderTracked() and renderTriggered() in the Option API.

Here is a syntax demo structure:

import { onRenderTracked, onRenderTriggered} from 'vue'

onRenderTracked((event) => {
   console.log('Tracked:', event)
 })

onRenderTriggered((event) => {
   console.log('Triggered by:', event)
 })

onActivated() and onDeactivated()

Vue calls these hooks only when the component is inside a <KeepAlive> wrapper. It calls onActivated() after inserting the component instance back into the DOM from the cached tree managed by KeepAlive. Use this hook to restore state, restart timers or refetch data when the component becomes active again.

The onDeactivated() hook is called after the component instance is removed from the DOM as part of a tree cached by KeepAlive>. It’s ideal for pausing timers, cancelling API polling or temporarily stopping reactive effects while the component is inactive. They are equivalent to the activated() and deactivated() in Option API.

onErrorCaptured()

Vue calls this hook when it captures an error in the component or any of its child components. This hook works like an error boundary: It lets you handle or suppress errors from children component to prevent them from crashing the entire app. In the Options API, this hook is equivalent to errorCaptured().

Here is a syntax demo structure:

import { onErrorCaptured } from 'vue'

 onErrorCaptured((err, instance, info) => {
   console.error('Captured error:', err)
   return false // prevent further propagation
 })

onServerPrefetch()

This hook is a special lifecycle hook used exclusively for server-side rendering (SSR) in Vue. It runs on the server before the component is rendered, allowing you to perform asynchronous data fetching ahead of time. This allows the component to be rendered with all the necessary data already available.

Here is a syntax demo structure:

import { onServerPrefetch } from 'vue'

setup() {
  onServerPrefetch(async () => {
    // Fetch your async data here
  })
}

The additional lifecycle hooks provide fine-grained control over component behavior in complex use cases such as debugging, error handling, server-side rendering and component activation/deactivation for improved performance and UX.

Wrapping Up

That’s a long read. Lifecycle hooks are your window into how Vue operates behind the scenes. Whether you’re building a simple component or architecting complex dynamic interfaces, understanding the functionalities of these hooks will help you write cleaner, more maintainable components.

That said, the true power of lifecycle hooks lies in how well you organize, optimize and clean up your logic within them. The way you handle this will directly impact the performance and maintainability of your components.

Below are a few best practices I recommend when working with lifecycle hooks:

• Organize your lifecycle hooks clearly and logically: Group related hooks together and follow a consistent order within your component. Doing this makes your code easier to follow and helps you (and your teammates) understand how the component behaves at each stage. For example, if you add an event listener in onMounted(), clean it up in onUnmounted() right afterward to keep related logic easy to trace.
• Avoid heavy operations inside lifecycle hooks: Avoid executing heavy tasks like large computations, complex DOM manipulations or intense loops directly within hooks such as onMounted() or onUpdated(). These operations can block the browser’s main thread, leading to performance issues.
• Always perform cleanup in onBeforeUnmount() or onUnmounted: Clean up side effects like intervals, timeouts, event listeners, subscriptions and third-party libraries when your component is unmounted.
• Keep logic declarative and reactive: Instead of managing DOM or state imperatively, lean into Vue’s reactivity system. Use computed() for derived values and watch() to react to changes. Avoid recalculating or updating state manually in lifecycle hooks when you can rely on Vue’s built-in tools.

To learn more deeply about lifecycle hooks in Option API, check out this link: Lifecycle Hooks with Options API.

Happy coding!

Do you ever see documentation websites that have a search feature and it’s super fast? Well, the novices decide to use a real database like Algolia and potentially pay for it. The pros use pure JavaScript.

TL;DR

Learn to create a Nuxt application that can search static data. Set the data as an object, then filter through the results in real time to get the desired page. This demo adds fuzzy search, uses scoring and handles multiple fields.

Nuxt

This demo uses Nuxt and assumes you have a basic understanding of composables, pages and layouts.

Layout

Create the default layout.

// layouts/default.vue

<template>
  <main class="min-h-screen bg-gray-100 text-gray-800">
    <div class="flex flex-col items-center py-8">
      <img src="https://www.telerik.com/bttf.webp" alt="Back to the Future man!" />
    </div>
    <div class="max-w-4xl mx-auto px-6">
      <slot />
    </div>
    <nav class="bg-white border-t border-gray-200 mt-12 py-8">
      <div class="max-w-4xl mx-auto px-6">
        <h2 class="text-xl font-bold text-blue-700 mb-4">
          Back to the Future Archive
        </h2>
        <ul class="grid grid-cols-1 sm:grid-cols-2 gap-3">
          <li>
            <NuxtLink to="/" class="hover:underline text-blue-600">
              Home
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/vehicles/delorean"
              class="hover:underline text-blue-600"
            >
              The DeLorean Time Machine
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/characters/marty"
              class="hover:underline text-blue-600"
            >
              Marty McFly
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/characters/doc-brown"
              class="hover:underline text-blue-600"
            >
              Doc Emmett Brown
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/timeline/hill-valley"
              class="hover:underline text-blue-600"
            >
              Hill Valley Timeline
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/tech/hoverboard"
              class="hover:underline text-blue-600"
            >
              Hoverboard Technology
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/characters/biff"
              class="hover:underline text-blue-600"
            >
              Biff Tannen's Antagonism
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/tech/flux-capacitor"
              class="hover:underline text-blue-600"
            >
              Flux Capacitor
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/timeline/1985-vs-2015"
              class="hover:underline text-blue-600"
            >
              1985 vs. 2015
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/events/enchantment-dance"
              class="hover:underline text-blue-600"
            >
              Enchantment Under the Sea Dance
            </NuxtLink>
          </li>
          <li>
            <NuxtLink
              to="/shop/merchandise"
              class="hover:underline text-blue-600"
            >
              Back to the Future Merchandise
            </NuxtLink>
          </li>
        </ul>
      </div>
    </nav>
  </main>
</template>

This is just some links to Back to the Future pages.

Create Catch-All Route

I didn’t feel like manually creating a bunch of pages, so I just generated them. In a real world app, you will probably have generated static files created in markdown. If you generate pages from a database, you would probably use the database itself to search.

// pages/[...slug].vue

<script setup lang="ts">
import { useRoute } from "vue-router";

const route = useRoute();

const fullPath = "/" + (route.params.slug as string[]).join("/");
const page = items.find((item) => item.url === fullPath);
</script>

<template>
  <div v-if="page">
    <h1>{{ page.title }}</h1>
    <p>{{ page.description }}</p>
  </div>
  <div v-else>
    <h1>404 - Page Not Found</h1>
    <p>The requested page does not exist.</p>
  </div>
</template>

Again, this is for demo purposes only.

Searching: The Actual Data

We want to store our data in a large object.

// composables/useSearch.ts

type BTTFItem = {
    title: string;
    description: string;
    url: string;
};

export const items: BTTFItem[] = [
    {
        title: "The DeLorean Time Machine",
        description: "Explore the iconic DeLorean, the time-traveling car built by Doc Brown.",
        url: "/vehicles/delorean"
    },
    {
        title: "Marty McFly",
        description: "Learn all about the skateboarding teenager who travels through time.",
        url: "/characters/marty"
    },
    {
        title: "Doc Emmett Brown",
        description: "Meet the eccentric inventor behind the time machine.",
        url: "/characters/doc-brown"
    },
    {
        title: "Hill Valley Timeline",
        description: "A deep dive into the changing history of Hill Valley across the trilogy.",
        url: "/timeline/hill-valley"
    },
    {
        title: "Hoverboard Technology",
        description: "Discover the future of personal transportation with hoverboards.",
        url: "/tech/hoverboard"
    },
    {
        title: "Biff Tannen's Antagonism",
        description: "Explore the many timelines where Biff makes life difficult for Marty.",
        url: "/characters/biff"
    },
    {
        title: "Flux Capacitor",
        description: "The core component that makes time travel possible.",
        url: "/tech/flux-capacitor"
    },
    {
        title: "1985 vs. 2015",
        description: "Compare the original 1985 to the future version envisioned in Part II.",
        url: "/timeline/1985-vs-2015"
    },
    {
        title: "Enchantment Under the Sea Dance",
        description: "The pivotal high school dance that almost erased Marty from existence.",
        url: "/events/enchantment-dance"
    },
    {
        title: "Back to the Future Merchandise",
        description: "Browse collectibles, clothes, and posters from the BTTF universe.",
        url: "/shop/merchandise"
    }
];

How Search Works

There is no secret to searching in Vanilla JS. We use a filter.

items.filter(item => item.title.includes(q));

Now, we must check for lowercase, check both title and description, deal with white space before and after, and handle signals.

useSearch

For our first simplest version, we create a composable.

export function useSearch() {

    const query = ref('');
    const results = ref<BTTFItem[]>([]);

    function search() {
        const q = query.value.trim().toLowerCase();
        results.value = q === ''
            ? []
            : items.filter(item =>
                item.title.toLowerCase().includes(q) ||
                item.description.toLowerCase().includes(q)
            );
    }
    return {
        query,
        results,
        search
    };
}

This composable searches through our items array and filters out the results.

Notice the items array is declared outside the hook itself, as we only need to declare the static data once.

Usage

We need to import the the composable and use it in our search component. Make sure to use proper separation of concerns and the single responsibility principle.

Keep the functionality in the composable.

<script setup lang="ts">
const { query, results, search } = useSearch();
</script>

<template>

  <div class="p-6 max-w-xl mx-auto relative">
    <input
      type="text"
      v-model="query"
      @input="search"
      placeholder="Search Back to the Future..."
      class="w-full rounded-lg border border-gray-300 px-4 py-3 text-sm shadow-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
    />

    <transition
      enter-active-class="transition duration-200 ease-out"
      enter-from-class="opacity-0"
      enter-to-class="opacity-100"
      leave-active-class="transition duration-150 ease-in"
      leave-from-class="opacity-100"
      leave-to-class="opacity-0"
    >
      <ul
        v-if="query && results.length"
        class="absolute left-0 right-0 mt-2 z-50 bg-white border border-gray-200 rounded-lg shadow-lg max-h-80 overflow-y-auto"
      >
        <li
          v-for="(item, index) in results"
          :key="index"
          class="hover:bg-gray-50 border-b border-gray-100 last:border-0"
        >
          <NuxtLink
            :to="item.url"
            class="block px-4 py-3 text-blue-600 font-medium"
          >
            {{ item.title }}
          </NuxtLink>
        </li>
      </ul>
    </transition>

    <transition
      enter-active-class="transition duration-200 ease-out"
      enter-from-class="opacity-0"
      enter-to-class="opacity-100"
      leave-active-class="transition duration-150 ease-in"
      leave-from-class="opacity-100"
      leave-to-class="opacity-0"
    >
      <p
        v-if="query && !results.length"
        class="absolute left-0 right-0 mt-2 z-50 bg-white border border-gray-200 rounded-lg shadow-lg px-4 py-3 text-center text-gray-500 italic"
      >
        No results found.
      </p>
    </transition>
  </div>
</template>

Vue has some beautiful transition effects that work great with Tailwind.

For basic filtering examples:

• Kendo UI for Vue Grid Filtering
• KendoReact Grid Search Bar

Fuzzy Search

I know, I know, you want more! You want to implement a basic fuzzy search too!

Version 1

function fuzzyMatch(source: string, target: string): boolean {
  source = source.toLowerCase();
  target = target.toLowerCase();

  let sIndex = 0;
  for (let i = 0; i < target.length; i++) {
    if (source[sIndex] === target[i]) {
      sIndex++;
    }
    if (sIndex === source.length) {
      return true;
    }
  }
  return false;
}

export function useSearch() {

  const query = ref('');
  const results = ref<BTTFItem[]>([]);

  function search() {
    const q = query.value.trim().toLowerCase();
    if (q === '') {
      results.value = [];
      return;
    }

    results.value = items.filter(item =>
      fuzzyMatch(q, item.title) || fuzzyMatch(q, item.description)
    );
  }

  return {
    query,
    results,
    search
  };
}

The fuzzyMatch algorithm checks if all characters match in order or not.

Example 1

fuzzyMatch("doc", "Doc Emmett Brown") // true

• Matches: d → found at index 0, o → index 1, c → index 2 (all in order ✅)

Example 2

fuzzyMatch("mcf", "Marty McFly") // true

• Matches: m (Marty), c (McFly), f (McFly)—all in order ✅

Example 3

fuzzyMatch("dcm", "Doc Emmett Brown") // false

• d matches, c matches—but there’s no m after c in the string ❌

If you want to ignore spaces, you can add:

source = source.replace(/\s+/g, '').toLowerCase();
target = target.replace(/\s+/g, '').toLowerCase();

Scoring

Now, let’s score the results so we can sort the order.

function fuzzyScore(query: string, text: string) {

    query = query.replace(/\s+/g, '').toLowerCase();
    text = text.replace(/\s+/g, '').toLowerCase();

    let score = 0;
    let lastIndex = -1;

    for (const char of query) {
        const index = text.indexOf(char, lastIndex + 1);
        if (index === -1) return 0;
        score += 1 / (index - lastIndex);
        lastIndex = index;
    }

    return score;
}

export function useSearch() {

    const query = ref('');
    const results = ref<BTTFItem[]>([]);

    function search() {
        const q = query.value.trim().toLowerCase();
        if (!q) {
            results.value = [];
            return;
        }

        results.value = items
            .map(item => {
                const scoreTitle = fuzzyScore(q, item.title);
                const scoreDesc = fuzzyScore(q, item.description);
                const totalScore = scoreTitle * 2 + scoreDesc;
                return { item, score: totalScore };
            })
            .filter(entry => entry.score > 0)
            .sort((a, b) => b.score - a.score)
            .map(entry => entry.item);
    }

    return {
        query,
        results,
        search
    };
}

Instead of returning a boolean, we return a score and use .sort() to sort by that score. This includes the description AND the title.

Beautiful!

This is just the beginning of what you can do, but now you have the fundamentals!

The future isn’t written yet.

Repo: GitHub
Demo: Vercel

I’ve been obsessed with useState in Nuxt since the first time I saw it. Other frameworks do not seem to share data as easily (looking at you, React Context). Nuxt has many options to store state, and it definitely makes these things easy. I love it so much, I even wrote versions for other frameworks.

TL;DR

Nuxt is the easiest framework to share data across components. You can use useState, provide and inject, or persist data across cookies with useCookie. Either way, no other framework makes it this easy.

useState

DO NOT confuse Nuxt’s useState with React’s useState. React’s version is much weaker. Nuxt’s useState, on the other hand, is awesome!

How It Works

Let’s say we want to share data across components. In other frameworks, including Vue itself, you have to prop drill shared data. It is not fun. Context, on the other hand, allows you to share data by setting a “key/value” pair, and using it anywhere. Nuxt does this automatically.

useState('count', () => 0)

The first parameter is the key. In any framework with a type of Context API you must set a key to get a value. The second parameter is the fallback. The fallback is used when there is no value belonging to that key; however, it is also used to store the initial value itself.

Usage

The recommended way to use it is to create a custom hook, or a custom composable.

export function useCount() {

return useState('count', () => 0)

}

This returns a reactive counter that can be used anywhere!

I know what you’re thinking. Why not just use a normal reactive variable?

export function useCount() {

return ref(0)

}

This seems logical, but if you use useCount in multiple components, the state does not get shared. You will have new counters for each implementation.

// component 1

<script setup lang="ts">
const count = useCount()
</script>

<template>
  <p>Count: {{ count }}</p>
  <button
    @click="
      () => {
        count++;
      }
    "
  >
    +
  </button>
</template>

// component 2
<script setup lang="ts">
const count = useCount()
</script>

<template>
<div> {{ count }} <div>
</template>

If we click the button, we want the counter to increment everywhere.

How Does It Really Work?

I got so obsessed with the simplicity, I researched the source code.

Global vs. Local

Nuxt has a global store. You can get the values anywhere using useNuxtApp().

export function useGlobalState<T>(key: string, init?: (() => T | Ref<T>)) {

    const nuxtApp = useNuxtApp()

    const state = toRef(nuxtApp.payload.state, key)

    if (state.value === undefined && init) {

        const initialValue = init()

        state.value = initialValue
    }
    return state
}

I created a very simplified, but working, version of useState(). You get the value from the global store, make it reactive and return it. If it doesn’t exist, create it, save it, return it.

export function useCount() {

return useGlobalState('count', () => 0)

}

This will work the exact same way as useState. Because it runs only once, it is called a singleton.

useLocalState

But what if you need a local version?

Usage

Sometimes you don’t want to save every state value to the global store. This can make it hard to do individual component testing, create portable or isolated components, and keep data encapsulated.

Provide / Inject

Inspired by Angular, you can set and get a context easily in Vue / Nuxt by providing and injecting.

provide(key, value)

inject(key, fallback_value)

Sometimes you may see the patterns:

export function setCount(initialValue: number) {
const count = ref(initialValue)
provide('count', count)
return count
}

export function getCount() {
return inject<Ref<number>>('count');
}

Generally, you set and get the items in different components. However, I don’t see why we can’t do the same pattern as useState here as well.

Local

export function useLocalState<T>(key: string, init?: (() => T | Ref<T>)) {

    const state = inject(key, undefined)

    if (state === undefined && init) {

        const initialValue = toRef(init())

        provide(key, initialValue)

        return initialValue
    }
    return state
}

Now we can set any state locally, just like useState.

Caveat

The state must be able to talk to the other state in a line. This means it must be nested. If I create two child components, and I set the first component with the counter, the second component WILL NOT be able to communicate with the other child component. Context is shared hierarchically, not between siblings.

<Count />
<!-- Doesn't have access to count -->
<Count />

However, you can initialize the counter in any parent so that they both have access to it.

<script setup lang="ts">
useLocalState("count", () => 0);
</script>

<template>
  <Count />
  <Count />
</template>

Now you can use useLocalState('count') anywhere in the children.

useCookie

Nuxt also has a magical way to get and set cookies on the frontend just like any other signal with ref.

const count = useCookie("count");

count.value = 10;

This will save the value to 10 and create the cookie.

You can use the value just like any other reference. The beauty of this is: it will persist! You’re not only saving a global value, you’re saving it to the cookie.

Default

There are a bunch of cookie options you can set, but to set the default value, you set a function in default just like you would with useState.

const count = useCookie("count", {
  default: () => 10
});

Bonus: Under the Hood

Cookies are a complex creature, but for the sake of explanation, I thought I would create a pseudocode version from the source code. It would require something as complex as the original to work correctly, but you get the gist.

export function useCookie(key, { default: init() }) {
  
  if (server) {
  const cookie = getServerCookie()
  if (cookie) {
    return getCookie(key)
  }
  const state = init()
  setCookie(key, state)
  return state
}

// browser
const cookie = getClientCookie()
if (cookie) {
return getCookie(key)
}
const state = init()
setCookie(key, state)
return toRef(state)

// !!! NOT REAL CODE, WILL NOT WORK

Saving data has never been so easy!

Demo: Vercel
Repo: GitHub

TL;DR

These demos use Vue and Nuxt to present audio files with default controls, auto-play and customizable actions for your own app’s needs. The concept should work in any JavaScript framework.

Display Sound with Controls

To add a sound into our app, we must use the <audio /> element with the src pointing to our filename.

<template>
    <div>
        <h2 class="text-2xl my-3">Let's go Mario!</h2>
        <audio autoplay src="/mario.wav" preload="auto" controls />
    </div>
</template>

By adding controls, the browser will display the default control options.

You will have options to download the audio file, change the playback speed, play and pause, and modify the volume.

Preloading

We can preload the audio file by adding preload="auto" and even earlier in the header if we want.

<link rel="preload" as="audio" href="/mario.wav" type="audio/wav">

The link tag will pre-download the file as soon as the HTML is parsed in the header, but the audio tag will preload the file.

Multiple Sources

If we have multiple versions of the file and we want to make sure our browser supports it, we could use the source tag as well, but I do not use it in our example.

<audio controls preload="auto">
  <source src="/audio/mario.mp3" type="audio/mpeg">
  <source src="/audio/mario.wav" type="audio/wav">
  Your browser does not support the audio element.
</audio>

Autoplay

If we add autoplay to our element, it will automatically play the audio file. However, this is ONLY after interaction to the webpage. You can see this in action by changing routes and clicking back home.

Laser Looping

Our laser gun example will loop the file over and over. We add the loop attribute if we want to repeat the sound. Again, this will only start playing after the page had had interaction.

Custom Controls

If you’re building a game or dynamic website, you’re going to want to customize your controls.

Audio Hook

We also need an audio hook to control our audio element.

export const useAudio = (filename: string) => {

    const audio = ref<HTMLAudioElement | null>(null)

    const isPlaying = ref<boolean>(false)
    const currentTime = ref<number>(0)
    const duration = ref<number>(0)

    const seek = () => {
        if (audio.value) audio.value.currentTime = currentTime.value
    }

    const updateTime = () => {
        if (audio.value) currentTime.value = audio.value.currentTime
    }

    const pause = () => {
        if (!audio.value) {
            return
        }
        if (audio.value.paused) {
            audio.value.play()
            return;
        }
        audio.value.pause()
    }

    onMounted(() => {

        if (!audio.value) {
            return
        }

        audio.value.src = filename
        audio.value.autoplay = true
        audio.value.ontimeupdate = updateTime
        audio.value.onplay = () => {
            isPlaying.value = true
        }
        audio.value.onpause = () => {
            isPlaying.value = false
        }
        audio.value.onloadedmetadata = () => {
            duration.value = audio.value!.duration
        }
    })

    return {
        audio,
        pause,
        isPlaying,
        currentTime,
        duration,
        seek
    }
}

Nuxt and other frameworks have libraries for this with many more features, so let’s break down how you can create one.

Signals

Anything that will require the DOM to update dynamically will need a signal.

const isPlaying = ref<boolean>(false)
const currentTime = ref<number>(0)
const duration = ref<number>(0)

Filename

We set our filename by passing it to the hook.

audio.value.src = filename

When the component gets mounted, so does the filename.

Attributes

Our autoplay and loop attributes are equally available.

audio.value.autoplay = true

isPlaying

Notice the isPlaying gets handled using the built-in onpause and onplay.

audio.value.onplay = () => {
    isPlaying.value = true
}
audio.value.onpause = () => {
    isPlaying.value = false
}
audio.value.onloadedmetadata = () => {
    duration.value = audio.value!.duration
}

Duration

We will need to calculate the duration of the audio file as soon as it is available.

audio.value.onloadedmetadata = () => {
    duration.value = audio.value!.duration
}

Play and Pause Button

We will need to toggle the play/pause correctly.

const pause = () => {
    if (!audio.value) {
        return
    }
    if (audio.value.paused) {
        audio.value.play()
        return
    }
    audio.value.pause()
}

If paused, we display play; if playing, we display pause.

Note: We can’t use the audio element until the reference is correctly attached to the hook with audio.value. We do nothing if not attached yet while loading.

Current Play Time

Instead of starting a clock when the audio starts playing, we can watch the ontimeupdate event.

audio.value.ontimeupdate = updateTime

We update our signal based on that time.

const updateTime = () => {
    if (audio.value) currentTime.value = audio.value.currentTime
}

Hook Usage

We call the hook inside our component.

<script setup lang="ts">
const { audio, isPlaying, pause, currentTime, duration, seek } =
  useAudio("/basketball.wav")
</script>

<template>
  <main class="flex items-center justify-center gap-5">
    <button
      type="button"
      class="p-3 border rounded-xl bg-blue-500 text-white font-bold cursor-pointer"
      v-on:click="pause"
    >
      {{ isPlaying ? "Pause" : "Play" }}
    </button>
    <audio ref="audio" preload="auto" />
    <input
      type="range"
      class="w-full accent-blue-500"
      min="0"
      :max="duration"
      step="0.1"
      v-model="currentTime"
      @input="seek"
    />
  </main>
</template>

Attach Element

const { audio, ... } = useAudio('/filename');

...

<audio ref="audio" preload="auto" />

Play Button

Since isPlaying is a signal, we can easily display the proper text.

{{ isPlaying ? "Pause" : "Play" }}

Seek with Input

We use an range input element to seek.

<input
  type="range"
  class="w-full accent-blue-500"
  min="0"
  :max="duration"
  step="0.1"
  v-model="currentTime"
  @input="seek"
/>

We can set our duration and currentTime, and when we change it, this will update the seek function.

This is just the beginning. Now go build something and listen to your sounds!

Demo: Vercel
Repo: GitHub

TL;DR

This article teaches you how to create an SVG progress circular component that can be used in custom components like games, character counts and charts. This example uses Vue and Nuxt, but it could be easily modified to work with any JS framework. It also uses Tailwind, but standard CSS works as well.

The Core Reusable Component

We allow the user to customize the component dimensions, put an HTML object inside it and keep it reactive.

<script setup lang="ts">
const {
  size = 150,
  width = 20,
  trailColor = "gray",
  strokeColor = "black",
  progress,
} = defineProps<{
  size?: number
  width?: number
  trailColor?: string
  strokeColor?: string
  progress: number | string
}>();

const cy = size / 2
const r = cy - width / 2
const circumference = 2 * Math.PI * r

const dashOffset = computed(() => circumference * (1 - Number(progress) / 100))
</script>

<template>
  <svg xmlns="http://www.w3.org/2000/svg" :width="size" :height="size">
    <circle
      :cx="cy"
      :cy
      :r
      :stroke="trailColor"
      fill="none"
      :stroke-width="width"
    />
    <circle
      :cx="cy"
      :cy
      :r
      fill="none"
      :stroke="strokeColor"
      :transform="`rotate(-90 ${cy} ${cy})`"
      :stroke-dasharray="circumference"
      :stroke-dashoffset="dashOffset"
      :stroke-width="width"
    />
    <foreignObject :x="0" :y="0" :width="size" :height="size">
      <div class="size-full flex items-center justify-center">
        <slot />
      </div>
    </foreignObject>
  </svg>
</template>

• Size – The SVG size
• Width – The SVG stroke width
• Trail Color – The Circle Color
• Stroke Color – The progress color
• Progress – The progress number (or string) between 1 and 100

Foreign Object

The proper way to put HTML inside SVG, is to use a foreign object. To make our alignment correct, we must keep our width and height full using Tailwind or CSS, but this could be done manually outside the component.

Progress Selector

This component allows you to select the progress between 1 and 100 with a range selector.

Range Component

We need custom CSS to style the Range component, as this is not standard using Tailwind.

<script setup lang="ts">
const progress = useProgress()
</script>

<template>
  <div class="flex items-center justify-center text-center gap-5 mt-10">
    <label class="block mb-2 text-md font-medium text-gray-900" for="progress">
      Progress
    </label>
    <input
      v-model="progress"
      class="h-2 bg-gray-200 rounded-lg appearance-none cursor-pointer"
      type="range"
      name="progress"
      min="0"
      max="100"
      step="5"
    >
  </div>
</template>

<style scoped>
input[type="range"]::-webkit-slider-thumb {
  appearance: none;
  height: 1rem;
  width: 1rem;
  background-color: black;
  border-radius: 9999px;
  cursor: pointer;
}

input[type="range"]::-moz-range-thumb {
  height: 1rem;
  width: 1rem;
  background-color: black;
  border-radius: 9999px;
  cursor: pointer;
}
</style>

Shared Progress

Nuxt has a useful feature called useState, which allows you to share state between components without prop drilling. You can share the state between the components manually using providers, injectors or context, depending on your framework.

**export const useProgress = () => {
    return useState('progress', () => 90);
};**

With this code, we can use useProgress in any component, and the state is shared across the component.

Progress Selector

We use the useProgress hook, and pass it to our <svg-circle /> component, as well as inside the slot to display the percent.

<script setup lang="ts">
const progress = useProgress()
</script>

<template>
  <div class="flex items-center justify-center text-center mt-10">
    <svg-circle :progress>
      <h1 class="text-2xl font-bold">{{ progress }}%</h1>
    </svg-circle>
  </div>
  <range-input />
</template>

We display the <range-input /> component and the progress signal inside the SVG circle. Works like a charm.

Note: We must keep the items in flex-center for proper alignment.

Word Counter

We set a character limit, compute the characters left and display the progress based on that number. With our core SVG component, this becomes extremely easy.

<script setup lang="ts">
const CHARACTER_LIMIT = 280

const content = ref("")

const progress = computed(
  () => ((content.value.length / CHARACTER_LIMIT) * 100) | 0
)

const display_characters = computed(
  () => CHARACTER_LIMIT - content.value.length
)

const color = computed(() =>
  display_characters.value < 0 ? "#dc2626" : "#1d4ed8"
)
</script>

<template>
  <div class="mx-10 mt-10">
    <label
      for="message"
      class="block mb-2 text-sm font-medium text-gray-900 dark:text-white"
      >Your message</label
    >
    <textarea
      id="message"
      v-model="content"
      rows="4"
      class="block p-2.5 w-full text-sm text-gray-900 bg-gray-50 rounded-lg border border-gray-300 focus:ring-blue-500 focus:border-blue-500"
      placeholder="Write here to see counter...."
    />
    <div class="flex items-center mt-5 gap-5">
      <svg-circle
        :progress
        :width="5"
        :size="50"
        :stroke-color="color"
        trail-color="#9ca3af"
      >
        {{ display_characters }}
      </svg-circle>
      <p>Characters Left</p>
    </div>
  </div>
</template>

We follow the same protocol of passing the progress to the <svg-circle /> component, and displaying the characters inside slot. This must be a signal as well to properly update the DOM.

Lingo Circle

The gamified button, similar to Duolingo, is really a matter of proper styling.

<script setup lang="ts">
const progress = ref(0)

const changePercent = () => {
  const tmp = progress.value + 20
  progress.value = tmp > 100 ? 0 : tmp
}
</script>

<template>
  <div class="flex flex-col items-center justify-center my-10 gap-5">
    <h1 class="font-bold">Lingo</h1>
    <div class="mx-50">
      <svg-circle
        :progress
        trail-color="#e5e7eb"
        stroke-color="#4ade80"
        :size="100"
        :width="10"
      >
        <button
          type="button"
          class="inline-flex rounded-full items-center justify-center whitespace-nowrap text-sm font-bold ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 uppercase tracking-wide bg-green-500 text-primary-foreground hover:bg-green-500/90 border-green-600 active:border-b-0 h-[70px] w-[70px] border-b-8 fill-primary-foreground text-primary-foreground"
          @click="changePercent"
        >
          <CrownSvg />
        </button>
      </svg-circle>
    </div>
  </div>
</template>

With our <svg-circle /> customizable, this makes creating any component easy. We can calculate our progress, which must be a signal, and pass it to the circle component as usual. Instead of using a number inside of our component slot, we simply use a styled button with an onclick handle.

The rest is up to your imagination!

Demo: Vercel
Repo: GitHub

Even easier? Check out the Progress Kendo UI for Vue ProgressBar, one of 110+ components professionally built with accessibility baked in.

With Vue 3 not only comes the ability to use the composition API but also the capacity to create components using script setup to minimize the amount of code we have to write. Script setup in itself is mostly syntactical sugar, and for that reason we have a few “magic” functions (or compiler macros if you want to be technical) that you should familiarize yourself with if you are going to be leveraging its capabilities.

defineProps

When creating a component with script setup, one of the first things you will probably run into is the need to create and define component properties.

In the options API, this is extremely clear as we define the props property in the object that is exported at the top level.

<script>
export default {
  props: {
    myProp: { type: String, required: true },
    optional: { type: Boolean, default: false } 
  }
}
</script>

To be able to achieve this in script setup, we use a magic function called defineProps. The function receives either an array of strings to define property names, or the same object syntax that you are already used to with the options API.

The above example, written in script setup and leveraging defineProps is written as follows:

<script setup>
defineProps({
  myProp: { type: String, required: true },
  optional: { type: Boolean, default: false } 
})
</script>

Note that if you want to use these props directly in your script, for example to create a computed property, you can capture the return value of the function—a reactive object.

<script setup>
const props = defineProps({
  myProp: { type: String, required: true },
  optional: { type: Boolean, default: false } 
})

const componentTitle = computed(() => props.optional ? 'Optional' : 'Required' )
</script>

For a simplified version, we can write this using array syntax. However, note that we lose the ability to warn our developers of type errors.

<script setup>
defineProps(['myProp', 'optional'])
</script>
defineEmits

defineEmits

A component will usually interact with other components through its public API which consists of props and emits. We just learned above how to declare props in our script setup components, but how do we go about declaring which events our component emits?

Just as we have defineProps, Vue 3 also grants us the defineEmits function. This function takes one parameter, an array of strings or an object—just as defineProps did.

Consider the following component that emits a click event.

<script setup>
const emit = defineEmits(['click'])
</script>

<template>
  <button @click="emit('click')" />
</template>

The component uses the defineEmits function to declare that this component will emit a click event. This helps reduce errors, as Vue will warn you if you emit an event that is not declared in the defineEmits declaration, and it allows us to also declare emit types—more on this in a second.

The defineEmits function returns another function which we name emit, and we use this function to emit the actual click event on our button input. This function can also be used internally within the script section to dynamically emit events when necessary.

If we wanted to be a bit safer, we can use object syntax (just like with our props) to declare a type of emit, and even a validator.

<script setup>
const props = defineProps({
  number: { type: Number, required: true }
})

const emit = defineEmits({
  click: {
    type: Number,
    validator: num => num > 0
  }
})

const emitValue = () => {
  emit(props.number + 1)
}
</script>

<template>
  <button @click="emitValue" />
</template>

There’s a couple of changes here. We’ve added a prop number to enhance our example. This allows us to add an emit value to our click event so that we can demonstrate the object syntax of defineEmits.

Notice that our click emit now declares a type of Number and even a validator that checks that the emitted value is always greater than 0. This is quite valuable and allows to catch errors in development early, as these warnings will be reported in browser console and test suites like Vitest.

Notice additionally that the emit function is now being used within the wrapper function emitValue. As described above, the function returned by defineEmits can be used to emit a value within the script block itself if needed.

defineModel

In Vue 3 the v-model defaults considerably changed from the way that they were declared in Vue 2. We now use modelValue as the default property for a model and update:modelValue for the default emit value of a v-model in a component. I will not go into depth on the new v-model syntax as this is out of the scope of the article. Instead, we will explore how we can leverage defineModel to quickly create several v-model-able properties within our component.

Consider the following example:

<script setup>
defineProps({
  modelValue: String,
  name: { type: String, default: 'Marina' }
})

defineEmits(['update:modelValue', 'update:name'])
</script>

defineModel allows us to quickly declare a “model” for both of the props above without having to declare them additionally in our emits.

<script setup>
const modelValue = defineModel({ type: String })
const name = defineModel('name', { type: String, default: 'Marina' })
</script>

Notice that the first defineModel call does not pass a string initially to declare the name of the model as modelValue. This is because modelValue is already the default, can we can safely skip it.

The second example creates the name property for us, and under the hood also declares the update:name emit so that the consuming component can bind to it using v-model:name syntax.

defineExpose

Components that are created using script setup syntax are closed by default. This means that unlike regular components, the properties that we create on the component will not be available to accessed using template refs or VM accessor in tests.

In order to make certain properties of our component available to be externally accessed in this manner, we must declare them as exposed with defineExpose as follows.

<script setup>
const privateProp = ref(123)
const publicProp = ref(234)

defineExpose({
  publicProp
})
</script>

If someone where to try to access our component’s publicProp through a $ref or through the .VM in a test, then component.publicProp would equal the reactive value of 234.

However, if someone tried to access the privateProp property, they would get undefined as that property is not publicly available.

Take note that exposing properties is to be used with extreme care and normally would be considered a code smell unless explicitly documented. Always err on the side of exposing a public API through an emit instead when possible.

defineOptions

In the options API, a component can be created declaring custom component options. These options are normally declare to provide a static property that is not reactive but useful to the internals of the component.

In order to declare options in a script setup component, we must declare it using the defineOptions function.

<script setup>
defineOptions({
  inheritAttrs: false,
  customOptions: {
    myOption: 123
  }
})
</script>

Notice that before creating our custom myOption option I’ve chosen to add an inheritAttrs call. I’ve done this on purpose because most of the time when you find yourself in need to declare options in a script setup component you will do it in order to control attribute fallthrough in your component.

Wrap-up

I hope this post has helped you understand these compiler macros for use in your Vue applications!

Imagine filling in a long form on a website, finally getting to the end, and clicking the submit button while starting to celebrate the job done. However, nothing happens. You decide to open the devtools, only to see a bunch of errors popping up when pressing the submit button again.

A situation like this can be very discouraging, and users often abandon websites after such ordeals. Fortunately, as developers, there are things we can do about reducing the chances of something like this happening. One of those is testing. In this article, we will cover how to set up and run tests with Vitest in a Vue application.

Why Is Testing Important?

An automated testing suite can be crucial for a success of an application, as it can improve application reliability, reduce the occurrence of bugs and increase the speed of delivering new features and updates to existing functionality.

With automated tests, developers can be more confident the code they wrote is bug free and won’t break existing functionality. There are three primary types of tests that can be used for Vue applications:

1. Unit Testing
Check the behavior of small functions, composables and components in isolation. For example, a unit test could check if a Tabs component works correctly and changes the active tab on a click.

2. Integration Testing
Assert multiple components and units work together in cohesion.

3. End-to-End (E2E) Testing
Simulate a real user and test the entire functionality flow from opening the browser, visiting the URL and interacting with the website to verify the frontend works seamlessly with the server and users are able to accomplish specific tasks.

There are pros and cons to each. While unit and integration tests can run faster, as most of the time they are tested in isolation without a need for API requests and interacting with any services, end-to-end tests can provide the most confidence, as they test that the whole system from the UI to the database works as expected.

What’s Vitest?

For many years, Jest was the testing framework of choice for JavaScript applications due to its robust functionality, mature community and plugin system, and compatibility with a lot of frameworks and libraries.

However, Jest can be quite slow in larger applications that might comprise hundreds or even thousands of files and tests. What’s more, it also doesn’t work well with modern tools such as Vite that rely on ES modules, as Jest uses CommonJS modules.

That’s where Vitest came into play. Vitest is a modern testing framework that is blazing fast in comparison to Jest and many other solutions. It has out-of-the-box support for ES modules, TypeScript, JSX and has Jest compatible API, which means migrating from Jest to Vitest is very straightforward.

It also has other interesting features, such as browser mode, in-source testing or type testing. You can find out more about all features in the documentation.

Project Setup with Vue, Vite and Vitest

The best way to learn to code is by practice, so let’s set up a new Vue project with Vite. After the setup, we will create a simple Vue component and then write unit tests with Vitest to test that the component works as expected. You can also find the full code for this article in this GitHub repository.

To scaffold a new Vue project, open the terminal and run the following command:

# npm 7+, extra double-dash is needed:
$ npm create vite@latest vue-vitest-basics -- --template vue

This command will create a new project in the vue-vitest-basics folder. After the installation is completed, change the directory into vue-vitest-basics and install vitest, @vue/test-utils and jsdom.

$ cd vue-vitest-basics
$ npm install -D vitest @vue/test-utils jsdom

If you’re wondering why we need to install @vue/test-utils, here’s the reason. Vitest itself is a test runner, but it’s framewor-agnostic. Therefore, it doesn’t know out of the box how to handle Vue components. For that, we need a separate library. @vue/test-utils is the official testing library provided by the Vue.js team. While there are other possible solutions, such as Vue Testing Library, in this article, we will focus on using @vue/test-utils.

Another library that we need to include is jsdom. By default, Vitest runs tests in the Node environment. However, Vue components need to be mounted in a browser-like environment. Since we will run our unit tests in Node, we need to configure Vitest to simulate the browser environment. We can do so by updating the vite.config.js file and adding test.environment config.

vite.config.js

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  test: {
    environment: "jsdom",
  },
});

Finally, you can start the development environment by running the command below.

$ npm run dev

You can visit http://localhost:5173 in your browser to see the starting page.

One more thing we need to do as part of the setup is to update the package.json file. Add a new test script that will run Vitest.

package.json

"scripts": {
  // other scripts 
  "test": "vitest"
}

We don’t have any test files yet, but we will get to it in a moment. You can already run the test command in the terminal to start Vitest.

Building a Simple Tabs Component

Let’s create a simple Tabs component that will render tab buttons based on the props provided. The Tabs component will accept two props: tabs and modelValue. The former will be an array of strings for each tab that should be displayed, while the former will represent the currently active tab. Here’s the code for the component.

src/components/Tabs.vue

<script setup>
const props = defineProps({
  tabs: {
    type: Array,
    default: () => [],
  },
  modelValue: {
    type: String,
  },
});

const emit = defineEmits(["update:modelValue"]);
</script>

<template>
  <div>
    <ul :class="$style.tab_list" role="tablist">
      <li
        v-for="tab of tabs"
        :key="tab"
        role="presentation"
      >
        <button
          type="button"
          :class="[
            $style.tab_button,
            tab === props.modelValue && $style.active,
          ]"
          role="tab"
          :id="`tab-${tab}`"
          :aria-selected="tab === props.modelValue"
          @click="emit('update:modelValue', tab)"
        >
          {{ tab }}
        </button>
      </li>
    </ul>
  </div>
</template>
<style module>
.tab_list {
  list-style: none;
  display: flex;
  align-items: center;
  gap: 1rem;
  border-bottom: 1px solid #ccc;
  padding: 0;
}

.tab_button {
  background: none;
  border: none;
  padding: 0.5rem 1rem;
  cursor: pointer;
  color: #007bff;
}

.active {
  border-bottom: 2px solid #007bff;
  background-color: green;
  color: white;
}
</style>

The Tabs component loops through the tabs array provided via props and renders a button for each tab. Whenever a tab is active, the active style is applied and the aria-selected attribute changes to "true".

Now, we can update the App.vue component, render the Tabs component, and see what it looks like in the browser.

src/App.vue

<script setup>
import Tabs from "./components/Tabs.vue";
const tabs = ["Home", "Profile", "About", "Settings"];
const activeTab = defineModel("activeTab");
</script>

<template>
  <div>
    <Tabs :tabs="tabs" v-model="activeTab" />
  </div>
</template>

You should see in the browser four tabs for Home, Profile, About and Settings.

Whenever a tab is clicked, its styles should change to reflect that.

Now that we have a working component, let’s write some unit tests to verify its functionality.

Unit Testing the Tabs Component with Vitest

The Tabs component is quite simple in its functionality, but there are a few things we can test to verify it’s working as expected:

1. The component renders the correct number of tabs, as provided via props.
2. A correct tab is set as active based on the modelValue prop.
3. The component emits an event when a tab is clicked and updates the active tab accordingly whenever the modelValue prop changes.
4. No buttons are rendered if the tabs prop doesn’t contain any items.

By writing tests for the aforementioned scenarios, we will cover how to:

• Mount and render Vue components
• Query elements and verify their contents and attributes
• Fire, intercept and verify events
• Update props programmatically

Let’s start by creating a new file called Tabs.spec.js in the src/components directory and writing the first test.

src/components/Tabs.spec.js

import { mount } from "@vue/test-utils";
import { describe, it, expect } from "vitest";
import Tabs from "./Tabs.vue";

const tabs = ["Home", "Profile", "About", "Settings"];

describe("Tabs.vue", () => {
  it("renders correct number of tabs", () => {
    const wrapper = mount(Tabs, {
      props: {
        tabs,
      },
    });

    const buttons = wrapper.findAll("button");

    expect(buttons).toHaveLength(4);
    for (const [index, tab] of Object.entries(tabs)) {
      expect(buttons[index].text()).toBe(tab);
    }
  });
});

The describe function collects and groups all the tests defined inside, while it separates tests. Our first test checks if the Tabs component renders the correct number of tabs. As I mentioned before, Vitest doesn’t know how to handle Vue component directly, so that’s where the mount from the @vue/test-utils library comes into play. The Tabs component receives the tabs array as a prop with four items—Home, Profile, About and Settings. After the component is mounted, we find all the buttons and verify their text content matches the items in the tabs array.

Now that we have the first passing test, we can add a few more. Let’s check if the component emits an update event when a tab is clicked, and whether it updates the active tab accordingly.

src/components/Tabs.spec.js

// ...other code
describe("Tabs.vue", () => {
  // ...other tests
 
  it("emits update:modelValue on tab click", async () => {
    const wrapper = mount(Tabs, {
      props: {
        tabs: tabs,
        modelValue: tabs[0],
      },
    });
    const buttons = wrapper.findAll("button");
    expect(buttons[0].attributes("aria-selected")).toBe("true");
    expect(buttons[1].attributes("aria-selected")).toBe("false");
    await buttons[1].trigger("click");

    expect(wrapper.emitted("update:modelValue")).toBeTruthy();
    expect(wrapper.emitted("update:modelValue")[0]).toEqual([tabs[1]]);

    await wrapper.setProps({
      modelValue: tabs[1],
    });

    expect(buttons[1].attributes("aria-selected")).toBe("true");
  });
})

In the new test, we set the first tab as active by passing the "Home" text to the modelValue prop. After the component is mounted, we verify that it’s active by checking the state of the aria-selected attribute.

We are going to test whether the active tab will change on click from the first tab the second one, so we also verify the second tab is in the inactive state. Afterward, the click event is triggered on the second tab by executing the trigger('click') method on the second tab button. Note that the trigger methods must be awaited, as otherwise the test will proceed executing other lines of code before Vue is able to update the state and re-render any changes that occurred as a result of the click. This could result in race conditions and unexpected test outcomes.

After the promise returned by the trigger method is resolved, we verify the Tabs component emitted the update:modelValue event and check the argument passed to it matches the text of the second tab.

Next, we change the modelValue prop to match the second tab. The reason we do it is because the Tabs component here is tested in isolation, and the active tab state is actually controlled by the parent component that renders it.

In our tests, the Tabs component doesn’t have any parent, and we are responsible for passing the props. That’s why we change the modelValue prop programmatically. Similarly to the trigger method, setProps returns a promise that must be awaited.

Finally, we verify that the second button is now active by asserting the aria-selected attribute is “true”.

Here is the code for a few more tests that check if the Tabs component correctly handles attributes, and empty values.

// ...other code
describe("Tabs.vue", () => {
  // ...other tests
  
  it("sets correct role and id attributes", () => {
    const wrapper = mount(Tabs, {
      props: {
        tabs,
      },
    });
    const button = wrapper.find("button");
    expect(button.attributes("role")).toBe("tab");
    expect(button.attributes("id")).toBe(`tab-${tabs[0]}`);
  });

  it("handles empty tabs array", () => {
    const wrapper = mount(Tabs, {
      props: {
        tabs: [],
      },
    });
    const lis = wrapper.findAll("li");
    expect(lis).toHaveLength(0);
  });

  it("does not set aria-selected if modelValue not in tabs", () => {
    const wrapper = mount(Tabs, {
      props: {
        tabs: tabs,
        modelValue: "Features",
      },
    });
    const buttons = wrapper.findAll("button");
    buttons.forEach(button => {
      expect(button.attributes("aria-selected")).toBe("false");
    });
  });

  it("handles missing modelValue", () => {
    const wrapper = mount(Tabs, {
      props: {
        tabs: tabs,
      },
    });
    const buttons = wrapper.findAll("button");
    buttons.forEach(button => {
      expect(button.attributes("aria-selected")).toBe("false");
    });
  });
})

Conclusion

In this article, we’ve explored the essentials of testing Vue applications using Vitest and @vue/test-utils. By setting up a testing environment with Vite and crafting unit tests for a simple Tabs component, we’ve demonstrated how to verify component behavior, manage props, handle events and verify reliability under various conditions.

Testing is a cornerstone of building robust and dependable Vue applications; it catches potential issues early and boosts confidence in your code. To take your testing skills further, consider experimenting with more advanced scenarios, such as testing components with slots, handling asynchronous operations or integrating with state management solutions like Pinia.

After spending a significant amount of my time working with Nuxt 3 this summer, I had to focus on designing a few authentication systems. I’ve explored various approaches, discovering that some are far simpler and more efficient than others.

In this article, I’ll share with you my most streamlined approach to managing authentication in Nuxt 3. ‍

What Solutions Are Available?

With the transition from Nuxt 2 to Nuxt 3, many developers might notice that familiar packages like @nuxtjs/auth are no longer viable. Fortunately for us, the Nuxt team is actively developing a new official module for Nuxt 3. ️‍♀️

In the meantime, there are three main solutions currently available:

1. Built-in Nuxt 3 utilities: Nuxt 3’s native utilities offer a straightforward, integrated approach to session management and authentication. This is the method I’ll focus on in this article.

2. nuxt-auth-utils: A minimalistic module maintained by Sebastien Chopin, nuxt-auth-utils provides essential tools for session management and OAuth integration. It’s lightweight yet powerful for many projects.

3. @sidebase/nuxt-auth: If you’re looking for a more feature-rich solution, this package is a strong contender. It supports OAuth providers, email-based authentication with Magic URLs and more. Leveraging the well-established Auth.js/NextAuth.js ecosystem, it’s ideal for more complex projects.

Key Differences Between nuxt-auth-utils and @sidebase/nuxt-auth

While both nuxt-auth-utils and @sidebase/nuxt-auth are excellent options, they cater to different needs. nuxt-auth-utils is a more streamlined solution, focusing on core utilities for session and OAuth management. On the other hand, @sidebase/nuxt-auth offers a broader range of features, including support for multiple authentication providers and enhanced session management capabilities, making it a robust choice for complex applications. ‍♀️

I haven’t had the chance to use any of these packages in production yet so I won’t cover them in this article. I thought they were worth mentioning, though, as they might be more suitable for your project’s requirements if the solution I’m about to present doesn’t meet your needs.

Leveraging Built-in Nuxt 3 Utilities

This approach is one I frequently use in various applications due to its simplicity and direct integration with Nuxt 3. This solution assumes that your backend handles authentication using tokens, such as JWT, and that these tokens are accessible via an API.

To implement this, you’ll need three components: a simple composable function (or a Pinia store), middleware to handle SSR and an Axios plugin to attach the token to the request headers. While you can use fetch or any other HTTP client, I prefer Axios due to familiarity.

Step 1: Create a Composable Function

Let’s start by creating a composable function to manage authentication:

// composable/useAuth.ts
export function useAuth() {
  // Custom composable to interact with your API
  const api = useApi()

  // Define reactive states for user and token
  const user = ref<null | User>(null)
  const opaqueToken = useState<null | string>('opaqueToken')

  // Function to handle login via email
  const loginWithEmail = async (params: {
    email: string
    password: string
  }) => {
    try {
      const { data: { opaqueToken, user } } = await api.auth.loginWithEmail({
        email: params.email,
        password: params.password,
      })

      opaqueToken.value = opaqueToken
      user.value = user

      return { user }
    } catch (error) {
      return Promise.reject(error)
    }
  }

  // Function to handle login via Google by exchanging the code for an opaque token
  const loginWithGoogle = async (params: {
    code: string
  }) => {
    try {
      const { data: { opaqueToken, user } } = await api.auth.loginWithGoogle({
        code: params.code,
      })

      opaqueToken.value = opaqueToken
      user.value = user

      return { user }
    }
    catch (error) {
      return Promise.reject(error)
    }
  }

  // Function to handle logout
  const logout = async () => {
    try {
      await api.auth.logout()

      opaqueToken.value = null
      user.value = null
    } catch (error) {
      return Promise.reject(error)
    }
  }

  // Watch for changes in the opaqueToken and sync with a cookie
  watch(opaqueToken, (newVal) => {
    const cookie = useCookie('opaqueToken')

    if (cookie.value !== newVal)
      cookie.value = newVal
  })

  return {
    opaqueToken,
    user,
    loginWithEmail,
    loginWithGoogle,
    logout,
  }
}

By invoking the loginWithEmail function anywhere in your application, you’ll have access to both the user data and the opaque token.

Step 2: Create a Middleware for SSR

Now let’s create a global middleware to share the opaque token between the server and the client. As you can see, we are using the useCookie composable as a proxy to share the opaque token between the server and the client. useState should be initialized on the server during SSR so it’s available immediately when the client hydrates.

// middleware/opaqueToken.global.ts

// Define a global middleware that will run for every route in the application
export default defineNuxtRouteMiddleware(() => {
  // Create or access a reactive state named 'opaqueToken'
  // This state will be available throughout the application
  const state = useState('opaqueToken')

  // Retrieve the value of the 'opaqueToken' cookie and assign it to the 'opaqueToken' state
  // This ensures that the state is always in sync with the cookie value
  // This synchronization is crucial for maintaining a consistent user session across server and client.
  state.value = useCookie('opaqueToken').value
})

This way, the token is always available and synchronized between SSR and CSR, maintaining a consistent user session.

Step 3: Set Up an Axios Plugin

Finally, let’s set up an Axios plugin to automatically include the opaque token in the authorization headers for each request:

// plugins/axios.ts
export default defineNuxtPlugin(() => {
  // Retrieve the 'opaqueToken' state
  const opaqueToken = useCookie('opaqueToken').value

  // Set the 'Authorization' header with the 'opaqueToken' value
  axios.interceptors.request.use((config) => {
    if (opaqueToken.value) {
      config.headers.Authorization = `Bearer ${opaqueToken.value}`
    }

    return config
  })
})

With this plugin, the opaque token is included in the authorization headers for each request, allowing the backend to authenticate the user.

Conclusion

And that’s all you need to implement a basic, yet effective, authentication system using built-in Nuxt 3 utilities! ‍♀️

Sometimes, the simplest solutions are the most powerful. After countless hours of trial and error, this approach has proven to be the most reliable and easy to implement. Whether you’re building a small project or a more complex application, this method provides a solid foundation for secure and efficient authentication.

If you found this article helpful, feel free to reach out to me on Twitter @RifkiNada. For more articles and insights, check out my work at www.nadarifki.com.

Thank you for reading!

The Composition API for Vue opened up a very powerful and flexible way of coding Vue components. A big part of this flexibility is the ability to create composables, which are, as described by the Vue docs, “a function that leverages Vue’s Composition API to encapsulate and reuse stateful logic.”

A problem that I’ve often encountered is that the way to test the use of these composables within a component is not immediately obvious, and can lead to the creation of bad practices.

In this article, we will explore how to test the use of a composable within a Vue 3 component with Jest and Vue Test Utils—the concepts, however, are directly translatable to Vitest.

Key Concepts

Before we dive into the code, I want to establish a couple of key concepts.

We will be leveraging the use of jest.mock to mock out the whole composable when testing it, this means that we will not be directly testing the internals of the composable. This is particularly important when testing composables that either make API calls internally or are provided by a third-party library.

It’s not uncommon in certain teams to avoid this in favor of deep testing the integration of a component with all of the dependencies, but this practice can be problematic as it breaks the concept of unit testing encapsulation. The bottom line is that a unit test that tests two different components or files is crossing into the territory of an integration test.

This does not in any case mean that you should not test the composable extensively, but it should be tested separately as a unit. As a consumer of that unit, the component that uses it should trust that the component’s contract input and output (I/O) is what it expects it to be, and any and all refactoring of the I/O of the unit should be treated as a breaking change within the bigger context of the codebase. (Whew.)

In some cases, however, such as simple composables that, for example, provide only a subset of computed values, it may be OK to not mock the returns of the function. However, in general, I recommend mocking the contents of these files in the component that imports them—otherwise, we’d be creating integration tests as stated previously.

Having laid out all that, let’s jump into the example.

The Code

Let’s assume that we have a composable that obtains data from our API’s endpoint for a user. Within this composable, a few network calls are happening, and the data is being parsed out into a few different computed properties that are returned out of the function so that we can check user permissions and state. Additionally, we will have an update function that would mutate the user’s configuration.

The internals of this composable are not important. The only thing we need to know as its consumer is the contract—what properties does this composable expect, and what will it return when I call it?

useUser.js

export const useUser = (userId) => {
  [...]

  return {
    update, // a function
    user, // a ref with the User object
    isEmployee // a computed Boolean
  }
}

Whenever we call the useUser composable, we know that will have to pass a userId to it and we will receive in return the three properties declared above.

Let’s create a simplified demo component that will use our useUser composable.

UpdateUserForm.vue

<template>
<form @submit.prevent="submit">
  <input data-testid="email" name="email" v-model="user.email" />
  <input data-testid="employee-id" v-if="isEmployee" name="employeeID" v-model="user.employeeID" />
</form>
</template>

<script setup>
import { useUser } from './useUser'

const props = defineProps({
  userId: { type: Number, required: true }
})

const { update, user, isEmployee } = useUser(props.userId)

const submit = async () => {
  try {
    await update(user.id, {
      email: user.value.email,
      employeeID: user.value.employeeID
    })
  } catch (e) {
    // handle error
  }
}
</script>

There’s a few things happening here so let’s take a deep look.

1. We are creating an extremely simplified version of a form for our user where we can edit both the email and, in the case that the user is an employee, their employee ID.
2. Note that the employee ID input will be displayed only in the case that the computed isEmploye is true—we will have to test for this.
3. When the user is submitted, it will call our submit method.
4. We import our useUser composable and call it with the userId received by the prop userId—we will want to test this. We extract the three returnable properties out of it by leveraging destructing.
5. Within our submit function we call the update function with the user’s ID as the first parameter and a second parameter we update the properties of the user email and employeeID with the updated values.
6. We are assuming for simplicity that it’s OK to mutate the user object returned to us by the composable. In some cases this may not be true, but we will use this as an example later on to clarify a point.

Now that we have our component, we can start writing our tests.

Testing the UpdateUserForm Component

The first thing we’ll want to test is that our useUser composable is getting called with the correct value. We don’t want to be in a situation where it’s not correctly receiving the user id as a property. For this we will have to already set up our mock, so let’s go through the code together.

UpdateUserForm.spec.js

import UpdateUserForm from './UpdateUserForm.vue'
import { useUser } from './useUser'
import { shallowMount } from 'vue@test-utils'
import { ref } from 'vue'

jest.mock('./useUser')

describe('UpdateUserForm', () => {
  const update = jest.fn()
  const user = ref({})
  const isEmployee = ref(false)
  
  beforeEach(() => {
    jest.clearAllMocks()

    user.value = { email: 'test@test.com', employeeID: null }
    isEmployee.value = false

    useUser.mockReturnValue({
      update,
      user,
      isEmployee
    })
  })

  it('passes the userId prop to the useUser composable', () => {
    const userId = 123
    shallowMount({
      props: { userId }
    })

    expect(useUser).toHaveBeenCalledWith(123)
  })
})

There’s a lot happening here, so let’s go step by step.

1. We are using jest.mock to mock out the whole /useUser file. We will control the return of the useUser function in line 16.
2. In a beforeEach call, we clearAllMocks on jest because we will be using jest.fn to keep track of the update function. We also use jest’s mockReturnValue to mock the return of the useUser composable. This means that we have to provide the returns for the composable here.
3. The first return update is declared above as a jest.fn, we declare it above as a const so that we can easily access this in all of our tests without having to reestablish the mockReturnValue in each test that we check for it. This may seem like overkill, but the re-mocking of the return value in every test can quickly bloat the document.
4. We are also declaring in lines 10 and 11 ref values for our user value and a ref for the isEmployee computed, later on inside the beforeEach block we reset the values of both of these values.

A couple of question may arise at this point, the first one being why are we using a ref to mock out a computed value?

The answer is for simplicity. You could absolutely set the isEmployee constant to a computed as so.

const isEmployee = computed(() => false)

However, this will make it a little challenging when writing tests as you will be able to easily change the return value of this property on the fly to check for different states of your component without having to re-mock the composable. This will make more sense when we write tests for it.

The second question that may arise is: why are we declaring the refs outside of the scope of all of our tests and then reseting them in the top most beforeEach block?

As you write more and more tests that use these values, you will be faced with two challenges. Either you have to make the choice of re-mocking the return values of the composable on every test or describe block to fit what you are trying to test, which can be overwhelming and error-prone, or keep them in a scope where they are accessible to all your tests.

For cleanliness, I recommend doing all of this in the highest level describe block of your test as shown here.

The second part of this is that we are choosing to reset the values of these refs beforeEach test because these refs will retain the value that the last test left them on as they are scoped outside of the tests themselves. We will use the top level beforeEach as a setup point for our whole test suite, so it makes sense to set the default values there. This is why the user ref is initially created with an empty object as a value, because this value is soon replaced.

Let’s move on and write a test that covers the v-if of our employee ID input.

UpdateUserForm.spec.js

import UpdateUserForm from './UpdateUserForm.vue'
import { useUser } from './useUser'
import { shallowMount } from 'vue@test-utils'
import { ref } from 'vue'

jest.mock('./useUser')

describe('UpdateUserForm', () => {
  const update = jest.fn().mockResolvedValue(true)
  const user = ref({})
  const isEmployee = ref(false)
  
  beforeEach(() => {
    jest.clearAllMocks()

    user.value = { email: 'test@test.com', employeeID: null }
    isEmployee.value = false

    useUser.mockReturnValue({
      update,
      user,
      isEmployee
    })
  })

  it('passes the userId prop to the useUser composable', () => {
    const userId = 123
    shallowMount({
      props: { userId }
    })

    expect(useUser).toHaveBeenCalledWith(123)
  })

  // NEW BLOCK
  describe('When the user is an employee', () => {
    beforeEach(() => {
      isEmployee.value = true
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(true)
    })
  })

  // NEW BLOCK
  describe('When the user is not an employee', () => {
    beforeEach(() => {
      isEmployee.value = false
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(false)
    })
  })
})

Let’s once again take a deep look.

1. We have opted for creating two describe blocks that accurately describe the state of the application that we want to test for. One of them will contain the tests for when our component is handling an employee, and one for when they are not. Notice that we added beforeEach blocks on each of them to clearly set up for the tests. In each of them we set the value of the isEmployee ref to either true or false as needed. We can rest assured that this value change will only affect these tests as we have established a reset for this earlier in the top level beforeEach block.
2. We then added a test for each of the scenarios.

At face value, this may seem like a lot of boilerplate and structure for such simple tests, and it is—but the reality is that in a production environment you will likely have quite a few more tests and complex scenarios. Having a good order and structure for your tests is always a good practice!

Let’s move on with the final portion of the tests, checking the ability of the user to submit the information.

UpdateUserForm.spec.js

import UpdateUserForm from './UpdateUserForm.vue'
import { useUser } from './useUser'
import { shallowMount, flushPromises } from 'vue@test-utils'
import { ref } from 'vue'

jest.mock('./useUser')

describe('UpdateUserForm', () => {
  const update = jest.fn()
  const user = ref({})
  const isEmployee = ref(false)
  
  beforeEach(() => {
    jest.clearAllMocks()

    user.value = { email: 'test@test.com', employeeID: null }
    isEmployee.value = false

    useUser.mockReturnValue({
      update,
      user,
      isEmployee
    })
  })

  it('passes the userId prop to the useUser composable', () => {
    const userId = 123
    shallowMount({
      props: { userId }
    })

    expect(useUser).toHaveBeenCalledWith(123)
  })

  describe('When the user is an employee', () => {
    beforeEach(() => {
      isEmployee.value = true
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(true)
    })

    // NEW
    it('calls the update function when the user submits the form', () => {
      const userId = 123
      const wrapper = shallowMount({
        props: { userId }
      })

      wrapper.find('[data-testid="email"]').setValue('email@test.com')
      wrapper.find('form').trigger('submit')
      
      await flushPromises()      

      expect(update).toHaveBeenCalledWith(userId, {
        email: 'email@test.com',
        employeeID: null
      })
    })
  })

  describe('When the user is not an employee', () => {
    beforeEach(() => {
      isEmployee.value = false
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(false)
    })
  })
})

In line 48, we added a new test to cover the submission of the form when the user is not an employee.

1. We find the email input and set its value to a new email and proceed to submit the form.
2. We need to await flushPromises as we have declared that the update function is going to return a Promise and is being awaited.
3. Finally we check that the update function (that was returned by the composable) is being called with the correct values.

An important thing to mention that may not be immediately obvious is that the user ref is being modified by the component whenever we update the value of one of the inputs, as the v-model bindings of each of the inputs is actually pointing to the user object.

I mentioned earlier that this may not be the case in your particular component, and this is not particularly a practice that I endorse, as mutating return values that are coming from a black box such as a composable leads frequently to problems and spaghetti code. However, I wanted to illustrate the importance of the ref management we made on the first beforeEach block.

If we had skipped the setting of the default values on this block, we would be in a situation where the tests following this one would be operating with the email we are setting on this test. This would be perhaps easy to pinpoint in a component as simple as this one, but, as your application grows in complexity, these kind of errors become extremely hard to pin down as they produce false positives in your tests.

Wrapping Up

Ref management and the way that we structure our unit tests needs to be a careful consideration with as much attention to detail and care as the actual component composition itself. As applications grow and become exponentially more complex, having good clean practices and management of your reactive values will save you many headaches.

There will come a time within most apps where you will have two pieces of your application that you wished shared a common reactive state. A good example of this is sharing the user information between a header component and a user edit form that is deeply nested in your application.

The Problem

Consider the following component tree for an app.

Say now that you need to get a user object that you fetched out of the API on the App component with both the Header and the UserForm. You certainly could start creating a prop and emits snakes and ladders down both trees, but in a more complex application where UserForm or any other component that requires access to shared reactive state this quickly can get out of hand.

The Solution(s)

Vue 3 comes with a couple of tools to handle such a problem. The first approach would be passing down the user object as required down through props as we mentioned before. This can get out of hand quickly as we could potentially be dealing with an N amount of components to put the prop down through, and if we later on need to add more properties to inject down the tree this can really add up.

A second approach would be to leverage provide and inject. This is beyond the scope of this article, but I can spoil it for you already and say that, while it is a solution, it’s not the best solution. Provide and inject are extremely powerful and flexible tools, and as any tool with the combination of these attributes it comes with a lot of drawbacks, especially when working with large teams or codebases as it can very quickly become unmanageable spaghetti.

A third approach when dealing specifically with state that is coming exclusively from your API is to use asynchronous state management libraries such as Tanstack Query if you have a RESTful API or Vue Apollo if you are using GraphQL. They are extremely powerful tools and you should get familiar with them (in my opinion), but they are designed for use with network data and not as a store.

The solution we will explore today is Pinia, a straightforward, easy-to-use state management store for Vue 3. This store allows us to share data between components and page in a seamless way while keeping a centralized state. Let’s take a look.

Setting Up Pinia

Setting Pinia up for a Vue 3 SPA is very straightforward. As usual, if you are building a new application from scratch, the npm or yarn create Vue script will ask you if you want to use Pinia as your state management of choice.

To incorporate it manually into your application or to add it to an existing app, we need to follow a couple of steps.

First, add the package to your application with either npm or yarn.

yarn add pinia
# or
npm install pinia

We then need to navigate to our app’s main.js or index.js (or wherever you are mounting your app) file and use Vue.use to add it to our application.

main.js

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
const app = createApp(App)

app.use(pinia)
app.mount('#app')

That’s it! Now we can move on to creating our very own user store.

Our First Pinia Store

We are going to create a user store to continue on with our made-up application example from the tree above. To add a store, we need to create a new file that will contain the code for it, I recommend you add these files under a stores folder to keep tidied up.

UserStore.js

import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {

})

To create a store, we use the defineStore method exposed by pinia. It takes two main params. The first one will be the id of the store; it can be anything you prefer, but it needs to be unique to your application—“user” makes the most sense for our example since this is what the store will be holding.

The second param is an object that holds the store’s options, let’s take a look at what we can add here.

State

The first property we will add to the options is the state, if you are familiar with Vue’s options API this will feel right at home, as the state for a store is basically the same thing. It is a function that returns an object that will hold all the state that we want this store to keep for us. For the sake of example we will add a user property and an isLoading flag.

UserStore.js

import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => {
    return {
      isLoading: false,
      user: null
    }
  }
})

As quick as that we can already import this store into our mock UserForm.vue component and make use of the isLoading and user states.

UserForm.vue

<template>
  <p v-if="store.isLoading">Loading!</p>
  <form> 
    <input :value="store.user.name" />
  </form>
</template>

<script setup>
import { useUserStore } from './stores/UserStore.js'
const store = useUserStore()
</script>

In the above example, we are importing the useUserStore and then calling the method. This returns to us a copy of the user store that we just created. The state in this store is shared, so any changes we do to it will of course be shared by any other components using the store.

Notice in the template we can now use the isLoading flag to check for the state and display a friendly message, and bind the user.name property to an input for later use.

Getters

Similar to computed values, we can create getters inside of our store. A straightforward example would be a getter that joins the user’s name and last name. Let’s give that one a shot.

UserStore.js

import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => {
    return {
      isLoading: false,
      user: null
    }
  },
  getters: {
    userFullName: (state) => state.user.name + ' ' + state.user.lastName
  }
})

As simply as it would be to create a computed property we now have a userFullName getter that we can use across our components. Let’s head to the mock Header.vue component and use it to display a message for our users.

Note that the getter does receive a param state with the store’s current state. It will contain any and all properties of state we created beforehand plus any other getters as well. Additionally, it’s important to keep in mind that getters can not be async!

Header.vue

<template>
<header>
  Welcome {{ store.userFullName }}
</header>
</template>

<script setup>
import { useUserStore } from './stores/UserStore.js'
const store = useUserStore()
</script>

Note that once again we import the store and call the useUserStore method to create it. This store points to the same state as the one we created before on the UserForm.vue file, so if the user changes their name it will also be reflected here.

The getter we created, userFullName, can be used directly from the store as shown in the above example.

Actions

The last option we can add to our store are actions, these are the equivalent of a component’s methods. As opposed to getters, methods can be async and can contain API calls. This is a good location to set up our logic to load the user’s data.

UserStore.js

import { defineStore } from 'pinia'
import { getCurrentUser } from './api/user'

export const useUserStore = defineStore('user', {
  state: () => {
    return {
      isLoading: false,
      user: null
    }
  },
  getters: {
    userFullName: (state) => state.user.name + ' ' + state.user.lastName
  },
  methods: {
    async loadUser () {
      this.isLoading = true
      
      const data = await getCurrentUser()
      this.user = data      

      this.isLoading = false
    }
  }
})

We’ve imported a mock getCurrentUser API call on the top of the file, this would most likely make a GET call to an endpoint to retrieve the user.

Then, we’ve created a new method on our store loadUser. This method sets the isLoading flag to true so that the user knows something is happening, and then makes an async call to the getUser method. When we receive the data back, we store it into our user state and then reset the isLoading flag to false.

A couple of things that are missing from this example are error handling and double-checking to see if we already have a user in the state before making a new network request to refetch it, but that’s outside of the scope of this article.

Now we can go back to our UserForm.vue component and call this method.

<template>
  <p v-if="store.isLoading">Loading!</p>
  <form> 
    <input :value="store.user.name" />
  </form>
</template>

<script setup>
import { useUserStore } from './stores/UserStore.js'
const store = useUserStore()

store.loadUser()
</script>

Now when our component loads, it will call the loadUser method of our store and load the user from the API. As soon as the user is loaded, the Header.vue component will display the userFullName getter we created. Remember, the user state is shared between all of the components that are using this store.

Wrapping Up

This merely scratches the surface of what you can do with Pinia. As with any library, I recommend taking a deep dive into their documentation as it is very well written and will help you learn not only the fundamentals but also the more intricate parts of this amazing library.

Nevertheless, you are now armed with the basics and can start writing your very own Pinia stores!

If you’ve read my previous articles, you know that I’m a Vue gal and that I love Nuxt! ‍♀️

In a nutshell, Nuxt is a powerful framework built on top of Vue that gives your Vue apps superpowers.

In this article, I discuss 10 important features of Nuxt 3 and why you should learn more about this framework if you are familiar with Vue. It’s another learning curve, but you will be able to enhance your Vue applications and take them to the next level.

Installing Nuxt

Creating a new Nuxt project is as easy as typing npx nuxi@latest init in your terminal. Head over the official installation page for more details.

But First, Say Hello to TypeScript

JavaScript is great, but have you ever had to deal with an error in production that you didn’t catch in the dev or staging environment because of a type mismatch?!

Yes, yes, I have, and many web developers have had to deal with that too. Especially when you’re in a small team and/or when you don’t have code reviews. It even happens, in very rare occurrences, in big teams with a staging server, code reviews and pre-prod environments.

So do yourself, your team and your clients a favor and use TypeScript to avoid bugs and maintain consistency throughout your codebase. The good news is that Nuxt 3 was built to be a first-class TypeScript citizen. To be honest, using Nuxt 3 without TypeScript seems like a strange choice to me. One of the reasons almost everyone switched to the Composition API is because of its better integration with TypeScript.

To give you one great example, you will be able to see right from your editor when you are sending something wrong to one component prop. In our projects, we usually put all of our types in a folder called types at the root. I will create a file called bases.d.ts inside with the following content.

type BaseButtonColor = 'blue' | 'gray' | 'green'

Now, in my BaseButton component, I will use something called PropTypes (that is automatically imported in Nuxt) like this:

<script lang="ts" setup>
// Props
const props = defineProps({
  color: {
    default: 'gray',
    type: String as PropType<BaseButtonColor>,
  },
})
</script>

If I try to use this BaseButton component somewhere and add the color red, your editor will warn you that this prop is not correct.

Of course, using TypeScript comes with many more benefits that you will discover along your journey, but believe me, once you make the switch, there is no going back.

Feature #1: Nuxt Makes Routing More Intuitive!

Nuxt 3 comes with an automatic file-based routing system, which simplifies the creation and management of your routes. As you remember, that’s different from Vue, where you have to set your routes manually. This means that now, you don’t have to get lost anymore in the maze that your router file becomes when your app scales up. ‍

In Nuxt, your file structure dictates your routes. Each file is a route. As you can see in the documentation, if you structure your files like this, for example:

| pages/
---| about.vue
---| index.vue
---| posts/
-----| [id].vue

This will automatically generate this router structure:

{
  "routes": [
    {
      "path": "/about",
      "component": "pages/about.vue"
    },
    {
      "path": "/",
      "component": "pages/index.vue"
    },
    {
      "path": "/posts/:id",
      "component": "pages/posts/[id].vue"
    }
  ]
}

Handy right!? ‍♀️

I’ve never had any issues with it, so I can’t recommend enough that you use the file system routing if you like it. It’s, in my opinion, the best way to quickly organize your application. As you can see, with Nuxt there is one less file to deal with. ‍

Feature #2: Nuxt Uses Convention over Configuration

What does convention over configuration mean and why should we care?

Nuxt favors predefined conventions and opinionated defaults over requiring developers to explicitly configure every aspect of their app. This approach saves us a lot of time and allows us to focus on writing the unique parts of our application rather than setting up the environment. Of course, it means that you have to follow the conventions, but it’s a small price to pay for the benefits it brings.

This is something I enjoy about Nuxt. Everything is properly organized, and you don’t have to think a lot about the structure of your application. You just follow the framework’s best practices. For example, Nuxt includes powerful middleware and layout systems that you can use right from the start. And if you need to create your own library of components, just use the Nuxt layers as it provides a lot of flexibility (and believe me, it was harder in the past; I even wrote an article about it). ‍♀️

Note: You are working with a higher level of abstraction, and things can sometimes seem magical, but the good news is that with the Nuxt DevTools, you can see everything that is happening under the hood. ‍♀️ P.S. Here is my Get Started with Nuxt DevTools piece.

Another powerful aspect of Nuxt 3 is its runtime configuration. When you need to manage different environments (development, staging, production) without needing to rebuild your application, this feature allows you to maintain consistent behavior across various environments with minimal effort.

My point is that by choosing a framework that embraces this philosophy, you will enhance your development workflow, maintain cleaner code and build scalable applications with ease. ‍

Feature #3: Nuxt Auto-Imports All Your Composables

One thing I enjoy about Nuxt 3 is that everything exported in your composable folder is available globally in your app. This is incredibly handy as it makes our developer experience more seamless (we don’t have to make sure the right thing is imported). You also have access to native composables or the ones coming from modules like useLocalePath, useI18n, useFetch, useAsyncData and many more. Additionally, managing cookies is made easy with the useCookies composable. ‍♀️

Note: If you need to see all the composables that are auto-imported, use the DevTools by going to imports or composables.

One thing I like is to have a composable useIcons where I put all my icons in one place. This way, I just have to call getIcon('myIcon'). For example, you can use Iconify, which is free and comes with thousands of icons from multiple packs.

const icons = {
  check: 'solar:check-circle-linear',
  chevronLeft: 'solar:alt-arrow-left-linear',
  chevronRight: 'solar:alt-arrow-right-linear',
} as const

export function getIcon(attribute: keyof typeof icons) {
  return icons[attribute] || icons.default
}

export type UIcon = keyof typeof icons

Feature #4: Nuxt Comes with Different Rendering Modes for Better Performance

Like Next for React, one of the killer features of Nuxt has always been its server-side rendering (also known as SSR). In contrast, Vue 3 requires additional setup and configuration for SSR.

To summarize what SSR is about, it simply means that the server will fully render the HTML page before sending it to the client. This will improve SEO, the initial load performance (compared to client-side rendering) and the overall user experience. I have dedicated an entire section about why Nuxt is a better choice for SEO than using Vue, but as you can guess SSR is one of the main reasons people got attracted to Nuxt. By allowing webpages to be displayed faster, we get them indexed more effectively by search engines.

Also, over the years, Nuxt has evolved, and four additional rendering modes are now available:

• Static Site Generation (SSG): This means the page is pre-rendered at build time, resulting in static HTML files that enhance performance and security. You will have many HTML files ready to be served to your users that you can easily deploy on a CDN like Netlify or Vercel.
• Client-Side Rendering (CSR): Like a classic Vue app, the page is entirely rendered in the browser. It may benefit highly interactive applications but results in slower initial load times.
• Hybrid Rendering: It combines SSR, SSG and CSR, allowing different pages or routes to use different rendering modes as needed. This is a great feature that allows you to choose the best rendering mode for each page of your application.
• And the last one… Edge-Side Rendering (ESR): I’ve never used it, but it offloads the rendering process of your page to the CDN’s edge servers. As explained in the documentation: When a request for a page is made, instead of going all the way to the original server, it’s intercepted by the nearest edge server. This server generates the HTML for the page and sends it back to the user. This process minimizes the physical distance the data has to travel, reducing latency and loading the page faster.

If you want to know more about the different rendering modes, I recommend you read the Nuxt documentation. ‍

Feature #5: Nuxt Will Make Your SEO Life Easier

We talked about SSR, but Nuxt 3 also comes with built-in composables that greatly enhance your SEO capabilities: useSeoMeta. You can easily set your meta tags inside your <head> section, titles and other SEO-related information with this composable. As Nuxt auto-imports all your composables, you can use it globally anywhere in your pages.

useSeoMeta({
  description: 'My awesome description',
  title: 'Welcome to my website',
  titleTemplate: 'Project | %pageTitle',
})

There are over 100 parameters that you can use. You can see the full list here. ‍

Additionally, there’s a fantastic package called Nuxt SEO that you will need. It is a collection of different modules that you can add to your app to easily deal with your sitemap (@nuxtjs/sitemap), your robots.txt (nuxt-simple-robots), your schema org or even to generate dynamic OG Images.

Note: If you use the Nuxt DevTools, take a look at the SEO section to see all your missing meta tags. It’s a great way to quickly check if everything is set correctly. ‍♀️

Feature #6: Nuxt Allows You to Write Your Own API

Nuxt 3 is a full-stack framework. This means you can write your own API directly in Nuxt. There’s no need to add another framework to your stack like Adonis or NestJS. Your backend logic, such as creating or managing user accounts, can be handled directly within Nuxt. ️‍♀️

For detailed information, check out the Nuxt API documentation. Take a moment to read through it because it’s really cool!

// server/api/hello.ts

export default defineEventHandler((event) => {
  return {
    hello: 'world'
  }
})

This is a significant advantage over Vue 3, which focuses primarily on the frontend and requires additional backend configuration to achieve similar functionality.

Note: By utilizing @sentry/vue, you can catch errors in your API routes, monitor what’s going wrong and continuously improve your app’s performance and reliability.

Feature #7: Data Fetching with Nuxt Is Easier

Nuxt 3 simplifies data fetching with composables like useAsyncData and useFetch. These composables are designed to work seamlessly with SSR, making it easier to manage asynchronous data fetching without the hassle of additional boilerplate code. They also provide additional options for handling loading states, errors and caching, enhancing the overall user experience.

<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/user', {
  pick: ['username', 'email', 'avatar']
})

// data: the result of the asynchronous function that is passed in.
// refresh: a function that can be used to refresh the data returned by the handler function.
// error: an error object if the data fetching failed.
// status: a string indicating the status of the data request ("idle", "pending", "success", "error").
// clear: a function which will set data to undefined, set error to null, set status to 'idle', and mark any currently pending requests as cancelled.
</script>

In contrast, Vue 3 requires you to manage data fetching manually with a library like Axios.

Feature #8: Nuxt Has an I18N Module to Create Multilingual Applications

If you know that your application will be in multiple languages, I can’t recommend Nuxt I18N enough to start with from the beginning. This module makes it easy to create multilingual applications, saving you a lot of time and effort in the future. ‍

It even allows you to use per-component translation (something I use intensively, as GitHub Copilot can easily translate for other languages).

<script setup lang="ts">
const { t } = useI18n({
  useScope: 'local'
})
</script>

<template>
  <p>{{ t('hello') }}</p>
</template>

<i18n lang="json">
{
  "en": {
    "hello": "hello world!"
  },
  "ja": {
    "hello": "こんにちは、世界!"
  }
}
</i18n>

Useful composables you will need all the time are: useLocalePath, useI18n and useSwitchLocalePath. ‍

Feature #9: Nuxt Has Nuxt Content, a Module to Manage Content

If you have a lot of content to write and want to use Markdown, use Nuxt Content. It will be automatically converted to HTML, making it ideal for blogs, documentation and static content.

You will have access to composables like queryContent to query your content, and you can even use your own Vue component inside your Markdown files.

::alert{type="warning"}
The **alert** component.
::

I always use Nuxt Content for articles, privacy policies and other content needs. Additionally, consider using Nuxt Studio, a CMS for Nuxt Content, though it comes at a cost.

Feature #10: Nuxt Comes with a Lot of Modules

I could not end this article without mentioning one big advantage of Nuxt: its rich ecosystem of modules. There is a module for almost everything you need, from authentication to PWA, analytics and more. And what’s best is that it is easy to add powerful features to your application with minimal configuration. ‍♀️

For example, it’s easy to create a dark mode with the @nuxtjs/color-mode module or optimize all your images with the @nuxt/image module.

So don’t reinvent the wheel, and take a look at the modules that are available. You will be surprised by how much time you can save by using them.

Conclusion

I hope I could convince you to have a look at Nuxt. Next time you start a new project, consider using Nuxt instead of Vue if it makes more sense to you. I am sure it will make your life easier and your applications better.

You can reach me on Twitter @RifkiNada. And in case you are curious about my work or other articles, you can look at them here www.nadarifki.com.

Thank you for reading!

☝️ Before we even dive in, let’s first answer a simple question: What do we consider a complex form in Vue?

Well, any form that has multiple steps. Take a shopping checkout process. Here, you’ll need state management to store the data as the customer navigates through different views.

The same applies for nested inputs when forms require organized sections for details like separate billing and shipping addresses. We will need to validate the values according to specific rules or use a state management system (spoiler alert: I will introduce you to our friends Zod and Pinia).

Another example is when you need to integrate with external APIs, like Google address validation API for real-time postal address verification. As we don’t control the response time, this comes with additional limitations we will have to take into account.

And let’s not forget fields that dynamically adapt to user input, such as the phone number field that displays the country name/flag as the user types it in.

So if you have to deal with any of these types of forms, you are in the right place to understand how to build forms in Vue that efficiently handle complex data and user interaction.

The Basics

Project Setup

✨ Together we will build a form for an educational app, ‍ where the user:

1. Selects the subject they want to study
2. Chooses the platforms from where we will compose the curriculum
3. Fills out a checkout form
4. Pays for the study package

‍ I know, this rocks!

Let’s set up our project using Vite:

1. Open your terminal and run npm create vite@latest in the folder of your choice.
2. Choose the following: Typescript + Vue Router + Pinia + Vitest + Cypress + ESLint + Prettier + Vue DevTools.
3. Open your project in VS Code using this command, like the cool kids do: cd the-name-of-your-project; code.
4. Run these commands in your VS Code built-in terminal:

npm install
npm run format
npm run dev

5. We will also be using Tailwind CSS. Follow these steps to get it up and running in your project:

npm install -D tailwindcss postcss autoprefixer;
npx tailwindcss init -p

• Then, in your tailwind.config.js:

content: [
  "./index.html",
  "./src/**/*.{vue,js,ts}",
],

• Then, import tailwind in your main.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

6. Now all you have to do is clean your components and views or you can download my version here. (I know, I could have told you earlier, but where is the fun in that?!)

Two-way Data Binding (v-model)

v-model is the glue that holds your data and UI in perfect harmony. It synchronizes in real time the state of your application with what the user interacts with. You will use this feature a lot when building forms in Vue.

For instance, if you have a username input, as soon as the user inputs their name (let’s say: nada), you can display a “Hello, nada!” without having to go through the hassle of setting up event listeners to detect changes and updates your data.

<!-- Random example -->

<template>
  <div>
    <input v-model="userName" placeholder="Enter your name" />
    <p>Hello, {{ userName }}!</p>
  </div>
</template>

<script>
import { defineComponent, ref } from 'vue';

export default defineComponent({
  name: 'GreetingExample',

  setup() {
    const userName = ref('');

    return { userName };
  }
});
</script>

Another neat feature of two-way data binding is that components and their parent components can communicate. Let’s see how this plays in our new app:

1. Create a FieldInput.vuecomponent:

<template>
  <div class="mb-4">
    <!-- Conditionally render the label if the 'label' prop is provided -->
    <label
      v-if="label"
      :for="id" 
      class="mb-2 block text-lg font-semibold text-gray-700"
    >
      {{ label }}
    </label>

    <!-- Input field bound directly to 'internalValue' using v-model -->
    <input
      :id="id"
      v-model="internalValue"
      :type="type"
      class="shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full sm:text-sm border-gray-300 rounded-md p-2 border"
      :placeholder="placeholder"
    />
  </div>
</template>

<script lang="ts">
import { defineComponent, computed } from 'vue'

export default defineComponent({
 name: 'FieldInput',

  // Define the props that this component accepts
  props: {
  id: {
    type: String,
    required: true
  },
  label: {
    type: String,
    default: ''
  },
  modelValue: {
    type: String,
    required: true
  },
  type: {
    type: String,
    default: 'text'
  },
  placeholder: {
    type: String,
    default: ''
  }
 },

  // Declare the events that this component can emit
 emits: ['update:modelValue'],

  setup(props, { emit }) {
    // Create a computed ref for internalValue
    // The getter returns the current value of the modelValue prop
    // The setter emits the 'update:modelValue' event when the value changes
    const internalValue = computed({
      get() {
        // Return the current value of modelValue prop
        return props.modelValue
      },
      set(value) {
        // Emit the 'update:modelValue' event with the new value
        emit('update:modelValue', value)
      }
  })

    return {
      // Return the computed ref to make it available in the template
      internalValue
    }
  }
})
</script>

2. Add your new component to the HomeView.vue:

<template>
  <div class="w-full min-h-screen">
    <form class="mt-40 p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2 lg:1/3">
      <FieldInput
        id="subject"
        label="Subject"
        v-model="subject"
        placeholder="Type the subject you want to learn here..."
      />
    </form>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref, onMounted } from 'vue'
import FieldInput from '@/components/fields/FieldInput.vue'

export default defineComponent({
  name: 'App',

  components: {
    FieldInput,
  },

  setup() {
    const subject = ref('')

    return {
      subject
    }
  }
})
</script>

Multi-step Forms, Nested Inputs, Dynamic Fields

Managing Fields Based on User Input: Dynamic Fields

Clean and user-friendly forms rely on dynamic fields—fields that are displayed based on the user’s input.

In our example, we will display a card selector when the user starts inputting the subject to study.

1. Let’s create our FieldCardSelector.vue:

<template>
  <div class="mb-4">
    <!-- Conditionally render the label if the 'label' prop is provided -->
    <label v-if="label" :for="id" class="mb-2 block text-lg font-semibold text-gray-700">
      {{ label }}
    </label>

    <!-- Input field bound directly to 'internalValue' using v-model -->
    <input
      :id="id"
      v-model="internalValue"
      :type="type"
      class="shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full sm:text-sm border-gray-300 rounded-md p-2 border"
      :placeholder="placeholder"
    />
  </div>
</template>

<script lang="ts">
import { defineComponent, computed } from 'vue'

export default defineComponent({
  name: 'FieldInput',

  // Define the props that this component accepts
  props: {
    id: {
      type: String,
      required: true
    },
    label: {
      type: String,
      default: ''
    },
    modelValue: {
      type: String,
      required: true
    },
    type: {
      type: String,
      default: 'text'
    },
    placeholder: {
      type: String,
      default: ''
    }
  },

  // Declare the events that this component can emit
  emits: ['update:modelValue'],

  setup(props, { emit }) {
    // Create a computed ref for internalValue
    // The getter returns the current value of the modelValue prop
    // The setter emits the 'update:modelValue' event when the value changes
    const internalValue = computed({
      get() {
        // Return the current value of modelValue prop
        return props.modelValue
      },
      set(value) {
        // Emit the 'update:modelValue' event with the new value
        emit('update:modelValue', value)
      }
    })

    return {
      // Return the computed ref to make it available in the template
      internalValue
    }
  }
})
</script>

2. Then in our HomeView.vue, we will display it only if our user has filled in the subject input (if subject.length > 0). This is something we can do thanks to the v-model and the computed that detects changes in the value of the subject input.

<template>
  <div class="w-full min-h-screen">
    <!-- Form to collect user inputs -->
    <form class="mt-40 p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2 lg:1/3">
      <!-- FieldInput component for entering the subject -->
      <FieldInput
        id="subject"
        label="Subject"
        v-model="subject"
        placeholder="Type the subject you want to learn here..."
      />

      <!-- Conditionally render FieldCardSelector based on the subject input -->
      <FieldCardSelector
        v-if="subject.length > 0"
        id="platforms"
        label="Platforms"
        v-model="selectedOptions"
        :options="options"
        class="mt-6"
      />
    </form>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref, onMounted } from 'vue'
import FieldInput from '@/components/fields/FieldInput.vue'
import FieldCardSelector from '@/components/fields/FieldCardSelector.vue'

// Define the Platform interface for type-checking
interface Platform {
  id: number
  name: string
  icon: string
  url: string
}

export default defineComponent({
  name: 'HomeView',
  components: {
    FieldInput,
    FieldCardSelector
  },
  setup() {
    // Holds the subject input value
    const subject = ref('') 
    // Holds the selected platform options
    const selectedOptions = ref<string[]>([])
    // Holds the list of platform options
    const options = ref<{ value: string; text: string; logo: string }[]>([])

    // Fetch platform options when the component is mounted
    onMounted(async () => {
      // Fetch platform data from a JSON file
      const response = await fetch('/platforms.json') 
      const data = await response.json()
      // Map the platform data to the options array
      options.value = data.platforms.map((platform: Platform) => ({
        value: platform.id.toString(),
        text: platform.name,
        logo: platform.icon
      }))
    })

    // Return state variables and methods to be used in the template
    return {
      subject,
      selectedOptions,
      options,
    }
  }
})
</script>

The options are fetched from this platforms.json:

{
  "platforms": [
    {
      "id": 1,
      "name": "Udemy",
      "icon": "/img/udemy.png",
      "url": "https://www.udemy.com/"
    },
    {
      "id": 2,
      "name": "YouTube",
      "icon": "/img/youtube.jpeg",
      "url": "https://www.youtube.com/"
    }
  ]
}

Preserving State Between Steps

Now, what happens when our user inputs the subject to study and platforms from which to fetch the courses? We create a curriculum based on the stated needs and move to the checkout page.

1. Let’s create our BaseButton.vue:

<template>
  <button
    :type="type"
    :class="[
      'inline-flex items-center justify-center px-4 py-2 border border-transparent text-md font-semibold rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2',
      {
        'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500': variant === 'primary',
        'bg-gray-600 text-white hover:bg-gray-700 focus:ring-gray-500': variant === 'secondary',
        'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500': variant === 'danger',
        'bg-white text-gray-700 border-gray-300 hover:bg-gray-50 focus:ring-indigo-500':
          variant === 'outline'
      }
    ]"
    @click="onClick"
  >
    <slot></slot>
  </button>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import type { PropType } from 'vue'

export default defineComponent({
  name: 'BaseButton',

  props: {
    type: {
      type: String as PropType<'button' | 'submit' | 'reset'>,
      default: 'button'
    },
    variant: {
      type: String as PropType<'primary' | 'secondary' | 'danger' | 'outline'>,
      default: 'primary'
    }
  },
  emits: ['click'],

  setup(props, { emit }) {
    const onClick = (event: Event) => {
      emit('click', event)
    }

    return {
      onClick
    }
  }
})
</script>

2. Now let’s add it to our form in HomeView.vue and use it to move to the next step where a preview of the curriculum we made is displayed:

<template>
  <div class="w-full min-h-screen">
    <form @submit.prevent="onGenerateCurriculum" class="mt-40 p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2">
      <FieldInput
        id="subject"
        label="Subject"
        v-model="subject"
        placeholder="Type the subject you want to learn here..."
      />

      <FieldCardSelector
        v-if="subject.length > 0"
        id="platforms"
        label="Platforms"
        v-model="selectedPlatforms"
        :options="options"
        class="mt-6"
      />

      <BaseButton
        v-if="subject.length && selectedPlatforms.length > 0"
        type="submit"
        variant="primary"
        class="mt-6 w-full"
      >
        Generate my Curriculum
      </BaseButton>
    </form>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';

import FieldInput from '@/components/fields/FieldInput.vue';
import FieldCardSelector from '@/components/fields/FieldCardSelector.vue';
import BaseButton from '@/components/base/BaseButton.vue';

import type { Platform } from '@/interfaces';

export default defineComponent({
  name: 'HomeView',

  components: {
    BaseButton,
    FieldInput,
    FieldCardSelector
  },
  setup() {
    const router = useRouter();

    const subject = ref('');
    const selectedPlatforms = ref<string[]>([]);

    const options = ref<{ value: string; text: string; logo: string }[]>([]);

    onMounted(async () => {
      const response = await fetch('/platforms.json');
      const data = await response.json();

      options.value = data.platforms.map((platform: Platform) => ({
        value: platform.id.toString(),
        text: platform.name,
        logo: platform.icon,
      }));
    });

    const onGenerateCurriculum = () => {
      router.push({
        name: 'PreviewView',
      });
    };

    return {
      subject,
      selectedPlatforms,
      options,
      onGenerateCurriculum
    };
  }
});
</script>

There is a slight little issue with our logic: How do we know in the next steps what the user has chosen? We could send it to the backend and then ask for it again in a call to the API when loading the next step but there must be a better way.

Enter the glorious concept of state management in Vue. Its role is simple: maintain data consistency and accessibility across all our components and views while simplifying its flow.

Using Pinia (or Vuex if you’re not that hip ), you can easily preserve your data while the user navigates steps in a complex form without having to always make endless calls to the backend. So let’s implement it together:

1. Create a useCourseStore.ts, where:

import { defineStore } from 'pinia';

// Define the store
export const useCourseStore = defineStore('course', {
  // State: Contains all the state variables that will be shared across the application
  state: () => ({
    subject: '', // Holds the subject the user wants to study
    selectedPlatforms: [] as string[], // Holds the list of selected platforms
  }),
  
  // Actions: Methods that can modify the state. They can also include business logic.
  actions: {
    // Sets the subject in the state
    setSubject(subject: string) {
      this.subject = subject;
    },
    // Sets the selected platforms in the state
    setSelectedPlatforms(platforms: string[]) {
      this.selectedPlatforms = platforms;
    },
  },

  // Getters: Methods to get derived state or perform calculations based on state
  getters: {
    // Returns the subject from the state
    getSubject: (state) => state.subject,
    // Returns the selected platforms from the state
    getSelectedPlatforms: (state) => state.selectedPlatforms,
  },
});

2. Modify the HomeView.vue and particularly the onGenerateCurriculum function to store the user’s input in the store:

<script lang="ts">
import { defineComponent, ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
// Import the useCourseStore function to access the store
import { useCourseStore } from '@/stores/useCourseStore';

import FieldInput from '@/components/fields/FieldInput.vue';
import FieldCardSelector from '@/components/fields/FieldCardSelector.vue';
import BaseButton from '@/components/base/BaseButton.vue';

import type { Platform } from '@/interfaces';

export default defineComponent({
  name: 'HomeView',

  components: {
    BaseButton,
    FieldInput,
    FieldCardSelector
  },
  setup() {
    const router = useRouter();
    // Initialize the course store to access and manipulate its state
    const courseStore = useCourseStore(); // Define 

    const subject = ref('');
    const selectedPlatforms = ref<string[]>([]);

    const options = ref<{ value: string; text: string; logo: string }[]>([]);

    onMounted(async () => {
      const response = await fetch('/platforms.json');
      const data = await response.json();

      options.value = data.platforms.map((platform: Platform) => ({
        value: platform.id.toString(),
        text: platform.name,
        logo: platform.icon,
      }));
    });

    const onGenerateCurriculum = () => {
      // Update the store with the current subject and selected platforms
      courseStore.setSubject(subject.value);
      courseStore.setSelectedPlatforms(selectedPlatforms.value);

      router.push({
        name: 'PreviewView',
      });
    };

    return {
      subject,
      selectedPlatforms,
      options,
      onGenerateCurriculum
    };
  }
});
</script>

See? It’s as easy as 1, 2, 3! Now, you only have to use the getters to call the data anywhere in your app.

Managing Nested Field Data

So now, our user is redirected to the checkout page after clicking on the Get my Curriculum call to action. And, of course, as with any checkout page, we have a billing address which is a nested field.

You can find the code for the preview page here:

• PreviewView.vue
• BaseCourse.vue
• BaseLoader.vue
• output.json
• platform.interface.ts
• course.interface.ts

Here is our CheckoutView.vue:

<template>
  <div class="w-full min-h-screen pt-40">
    <form @submit.prevent="onCheckout" class="p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2">
      <div class="md:grid md:grid-cols-2 md:gap-3">
        <FieldInput id="firstName" label="First Name" v-model="firstName" placeholder="Ada" />

        <FieldInput id="lastName" label="Last Name" v-model="lastName" placeholder="Lovelace" />
      </div>

      <FieldInput
        id="email"
        label="Email"
        v-model="email"
        type="email"
        placeholder="ada@example.com"
      />

      <FieldInput id="address" label="Billing Address" v-model="address" placeholder="address" />

      <div class="md:grid md:grid-cols-3 md:gap-3">
        <FieldInput id="zip" v-model="zip" placeholder="zip code" />

        <FieldInput id="city" v-model="city" placeholder="city" />

        <FieldInput id="country" v-model="country" placeholder="country" />
      </div>

      <BaseButton type="submit" variant="primary" class="mt-6 w-full">
        Send me my Curriculum
      </BaseButton>
    </form>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'

import FieldInput from '@/components/fields/FieldInput.vue'
import BaseButton from '@/components/base/BaseButton.vue'

export default defineComponent({
  name: 'CheckoutView',

  components: {
    BaseButton,
    FieldInput
  },
  setup() {
    const firstName = ref('')
    const lastName = ref('')
    const email = ref('')
    const address = ref('')
    const zip = ref('')
    const city = ref('')
    const country = ref('')

    const onCheckout = () => {
      console.log('Checkout', {
        firstName: firstName.value,
        lastName: lastName.value,
        email: email.value,
        fullAddress: `${address.value}, ${zip.value}, ${city.value}, ${country.value}`,
      })
    }

    return {
      firstName,
      lastName,
      email,
      address,
      zip,
      city,
      country,
      onCheckout
    }
  }
})
</script>

For now, I’m just console-logging the data our user gives us. But, as you can see with our billing address nested inputs, you may need to send the full address to your backend.

Input Validation

So far we haven’t added any validation to our form. Let’s see together what input validation we can put in place.

Built-in Validation

I classify built-in validation features into three categories:

• UX design
• HTML5 input attributes
• And, of course, Vue’s built-in validation features

Building input validation into the UX may not seem like the first thing you’d think of as a developer or as a designer, but developers and designers with enough experience know that integrating validation when designing the UX is crucial to minimize friction and provide a clear and seamless experience.

This is why, in the first part of our form, we only display the platform’s field card selector after the user has typed in a subject. The user also cannot move to the next step, as we don’t display the button until they’ve chosen at least one platform.

This was done using just two lines of code in HomeView.vue: v-if="subject.length > 0" and v-if="subject.length && selectedPlatforms.length > 0".

<form @submit.prevent="onGenerateCurriculum" class="p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2">
  <FieldInput
    id="subject"
    label="Subject"
    v-model="subject"
    placeholder="Type the subject you want to learn here..."
  />

  <FieldCardSelector
    v-if="subject.length > 0"
    id="platforms"
    label="Platforms"
    v-model="selectedPlatforms"
    :options="options"
    class="mt-6"
  />

  <BaseButton
    v-if="subject.length && selectedPlatforms.length > 0"
    type="submit"
    variant="primary"
    class="mt-6 w-full"
  >
    Generate my Curriculum
  </BaseButton>
</form>

I know, neat! This approach helps users know exactly what they need to do without any hassle for them and the developer too!

Let’s now, use HTML5 and Vue’s built-in validation features in our CheckoutView.vue.

Right now, when you click on the “Send me my curriculum” button without filling in any input, the console log is empty and nothing on the screen shows that something must be filled.

It is, to say the least, very confusing for a user!

Let’s fix that by first requiring every field in this form:

1. Go to FieldInput.vue and add the required attribute to the input tag add the required prop and set it to false:

<template>
    ...

    <input
      :id="id"
      v-model="internalValue"
      :required="required"
      :type="type"
      class="shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full sm:text-sm border-gray-300 rounded-md p-2 border"
      :placeholder="placeholder"
    />
    
...
</template>

<script lang="ts">
...

export default defineComponent({
  ...

  props: {
    ...
    required: {
      type: Boolean,
      default: false
    },
    ...
  },

  ...
})
</script>

2. Set the required prop to true in CheckoutView.vue on every field input:

<template>
  <div class="w-full min-h-screen pt-40">
    <form @submit.prevent="onCheckout" class="p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2">
      <div class="md:grid md:grid-cols-2 md:gap-3">
        <FieldInput id="firstName" label="First Name" v-model="firstName" placeholder="Ada" required />

        <FieldInput id="lastName" label="Last Name" v-model="lastName" placeholder="Lovelace" required />
      </div>

      <FieldInput
        id="email"
        label="Email"
        v-model="email"
        type="email"
        placeholder="ada@example.com"
        required
      />

      <FieldInput id="address" label="Billing Address" v-model="address" placeholder="address" required />

      <div class="md:grid md:grid-cols-3 md:gap-3">
        <FieldInput id="zip" v-model="zip" placeholder="zip code" required />

        <FieldInput id="city" v-model="city" placeholder="city" required />

        <FieldInput id="country" v-model="country" placeholder="country" required />
      </div>

      <BaseButton type="submit" variant="primary" class="mt-6 w-full">
        Send me my Curriculum
      </BaseButton>
    </form>
  </div>
</template>

Using only HTML5 required attribute you can at least tell your user what’s missing now. You will notice also that the console log isn’t executed until all inputs are filled.

The cherry on the cake is the email validation. That’s because we used the type="email" attribute for the email field input.

Here you can find all the attributes available for inputs.

Let’s improve on what we have done so far using Vue’s reactivity to display clear error messages to our users:

1. First, let’s change our FieldInput.vue to include an error message using an errorMessage and an onBlur function ➕ change the field’s border and outline color to red when the error message is displayed:

<template>
  <div class="mb-4">
    ...

    <input
      :id="id"
      v-model="internalValue"
      :required="required"
      :type="type"
      @blur="onBlur"
      :class="[
        'shadow-sm block w-full sm:text-sm rounded-md p-2 border outline-none focus:ring-1',
        required && errorMessage.length > 0 ? 'border-red-500 focus:ring-red-500 focus:border-red-500' : 'border-gray-300 focus:ring-indigo-500 focus:border-indigo-500'
      ]"
      :placeholder="placeholder"
    />

    <div v-if="required && errorMessage.length > 0" class="text-sm text-red-500 mt-1">
    {{ errorMessage }}
    </div>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref, computed } from  'vue'

export default defineComponent({
  ...

  props: {
    required: {
      type: Boolean,
      default: false
    },
    errorMessage: {
      type: String,
      default: ''
    },
    ...
  },

  ...

  setup(props, { emit }) {
    const touched = ref(false)

    ...

    const showError = computed(() => {
      return touched.value && props.errorMessage.length > 0
    })

    const onBlur = () => {
      touched.value = true
    }

    return {
      internalValue,
      showError,
      onBlur
    }
  }
})
</script>

2. Then in the CheckoutView.vue, we will add the errorMessage prop we created. The text for the error message will be generated through the getError function:

<template>
  <div class="w-full min-h-screen pt-40">
    <form @submit.prevent="onCheckout" class="p-6 mx-auto md:shadow-2xl rounded-lg md:w-1/2">
      <div class="md:grid md:grid-cols-2 md:gap-3">
        <FieldInput
          id="firstName"
          label="First Name"
          v-model="firstName"
          placeholder="Ada"
          required
          :error-message="getError('First Name')"
        />

        <FieldInput
          id="lastName"
          label="Last Name"
          v-model="lastName"
          placeholder="Lovelace"
          required
          :error-message="getError('Last Name')"
        />
      </div>

      <FieldInput
        id="email"
        label="Email"
        v-model="email"
        type="email"
        placeholder="ada@example.com"
        required
        :error-message="getError('Email')"
      />

      <FieldInput
        id="address"
        label="Billing Address"
        v-model="address"
        placeholder="address"
        required
        :error-message="getError('Address')"
      />

      <div class="md:grid md:grid-cols-3 md:gap-3">
        <FieldInput
          id="zip"
          v-model="zip"
          placeholder="zip code"
          required
          :error-message="getError('Zip Code')"
        />

        <FieldInput
          id="city"
          v-model="city"
          placeholder="city"
          required
          :error-message="getError('City')"
        />

        <FieldInput
          id="country"
          v-model="country"
          placeholder="country"
          required
          :error-message="getError('Country')"
        />
      </div>

      ...
    </form>
  </div>
</template>

<script lang="ts">
...

export default defineComponent({
  ...
  
  setup() {
    ...

    const getError = (fieldName: string) => {
      if (fieldName === 'Email' && email.value && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value)) {
        return 'Invalid email'
      } else {
        return `${fieldName} is required`
      }
    }

    return {
      firstName,
      lastName,
      email,
      address,
      zip,
      city,
      country,
      onCheckout,
      getError
    }
  }
})
</script>