Creating a custom composable in Vue - Mechanics & Internals

Overview - Creating a custom composable

What is it?

A custom composable in Vue is a reusable function that uses Vue's Composition API features like reactive state and lifecycle hooks. It helps you organize and share logic across different components without repeating code. Think of it as a small tool you create to handle a specific task that many parts of your app need.

Why it matters

Without custom composables, you would have to copy and paste the same logic in many components, making your code messy and hard to maintain. Custom composables let you write clean, organized, and reusable code, saving time and reducing bugs. They make your app easier to grow and change.

Where it fits

Before learning custom composables, you should understand Vue's Composition API basics like reactive state, refs, and lifecycle hooks. After mastering custom composables, you can explore advanced patterns like composable libraries, testing composables, and integrating with Vue Router or Vuex.

Mental Model

Core Idea

A custom composable is a function that bundles reactive state and logic so you can reuse it easily across Vue components.

Think of it like...

It's like creating a special kitchen gadget that you use whenever you cook a certain dish, instead of making the same steps by hand every time.

┌─────────────────────────────┐
│ Custom Composable Function   │
│ ┌─────────────────────────┐ │
│ │ Reactive State & Logic  │ │
│ └─────────────────────────┘ │
└─────────────┬───────────────┘
              │
  ┌───────────┴───────────┐
  │ Used in Multiple Vue   │
  │ Components to Share    │
  │ Behavior & Data        │
  └───────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Vue Composition API Basics

Concept: Learn the core tools like ref, reactive, and lifecycle hooks that custom composables use.

Vue's Composition API lets you create reactive variables with ref() and reactive(). You can also run code at certain times using lifecycle hooks like onMounted(). These are the building blocks for custom composables.

Result

You can create reactive data and run side effects inside Vue components.

Understanding these basics is essential because custom composables are just functions that use these tools to package logic.

2

Foundation

What Is a Custom Composable Function?

Concept: A custom composable is a plain function that uses Composition API features and returns reactive data or methods.

You write a function starting with 'use' (like useCounter) that creates reactive state and functions inside it. Then you return those so components can use them.

Result

You have a reusable function that components can call to get shared reactive behavior.

Knowing that composables are just functions helps you see they are simple and flexible tools.

3

Intermediate

Creating a Simple Counter Composable

🤔Before reading on: do you think the composable should return the reactive state directly or a copy? Commit to your answer.

Concept: Build a composable that tracks a number and provides increment and decrement functions.

import { ref } from 'vue'; function useCounter() { const count = ref(0); function increment() { count.value++; } function decrement() { count.value--; } return { count, increment, decrement }; } // Components can import and call useCounter() to get this behavior.

Result

Multiple components can share the same counter logic without repeating code.

Returning the reactive ref allows components to stay in sync with the state inside the composable.

4

Intermediate

Using Lifecycle Hooks Inside Composables

🤔Before reading on: can you use onMounted inside a composable or only inside components? Commit to your answer.

Concept: Composables can use lifecycle hooks to run code at specific times, just like components.

import { onMounted } from 'vue'; function useLogger() { onMounted(() => { console.log('Component mounted!'); }); } // When a component calls useLogger(), it logs on mount.

Result

You can add side effects and setup code inside composables that run with the component lifecycle.

Knowing composables can use lifecycle hooks makes them powerful for setup and cleanup logic.

5

Intermediate

Sharing State Across Components with Composables

🤔Before reading on: do you think calling a composable multiple times shares the same state or creates new state each time? Commit to your answer.

Concept: By default, each call to a composable creates new state, but you can share state by defining it outside the function.

import { ref } from 'vue'; let sharedCount = ref(0); function useSharedCounter() { function increment() { sharedCount.value++; } return { count: sharedCount, increment }; } // All components using useSharedCounter share the same count.

Result

You can create global-like reactive state shared by many components.

Understanding this helps you control when state is isolated or shared, avoiding bugs.

6

Advanced

Handling Parameters and Options in Composables

🤔Before reading on: do you think composables can accept arguments to customize behavior? Commit to your answer.

Concept: Composables can take parameters to make them flexible and reusable in different situations.

import { ref } from 'vue'; function useCounter(initialValue = 0) { const count = ref(initialValue); function increment() { count.value++; } return { count, increment }; } // You can create counters starting at different numbers.

Result

Composables become more adaptable and useful across your app.

Knowing composables accept parameters lets you build versatile tools instead of fixed logic.

7

Expert

Avoiding Common Pitfalls with Reactive References

🤔Before reading on: do you think returning reactive objects directly can cause unintended mutations outside the composable? Commit to your answer.

Concept: Returning reactive state directly can expose internal state to unwanted changes; sometimes you want to return readonly or computed values.

import { ref, readonly } from 'vue'; function useSafeCounter() { const count = ref(0); function increment() { count.value++; } return { count: readonly(count), increment }; } // Components can read count but cannot change it directly.

Result

You protect internal state from accidental modification, improving reliability.

Understanding how to control state exposure prevents bugs and enforces good encapsulation.

Under the Hood

Custom composables are just JavaScript functions that run inside Vue's reactive system. When you call a composable, it creates reactive references or reactive objects that Vue tracks for changes. Vue's reactivity system uses proxies to detect when data changes and updates the UI automatically. Lifecycle hooks inside composables register callbacks tied to the component instance that called them, so they run at the right time.

Why designed this way?

Vue designed composables as plain functions to keep them simple and flexible. This avoids complex class hierarchies or special syntax. Using JavaScript functions means you can compose logic naturally and reuse it anywhere. The Composition API was created to solve problems with large components and code reuse that the older Options API struggled with.

┌───────────────────────────────┐
│ Vue Component Calls Composable │
└───────────────┬───────────────┘
                │
      ┌─────────┴─────────┐
      │ Custom Composable  │
      │ - Creates reactive │
      │   refs/reactive    │
      │ - Registers hooks  │
      └─────────┬─────────┘
                │
      ┌─────────┴─────────┐
      │ Vue Reactivity     │
      │ System Tracks Data │
      │ Changes & Updates  │
      └───────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does calling a composable multiple times share the same state by default? Commit to yes or no.

Common Belief: Calling a composable multiple times always shares the same reactive state.

Reality: Each call to a composable creates new reactive state unless you explicitly share it outside the function.

Why it matters: Assuming shared state causes bugs where components don't behave independently or unexpectedly share data.

Quick: Can you use lifecycle hooks only inside components? Commit to yes or no.

Common Belief: Lifecycle hooks like onMounted can only be used inside Vue components.

Reality: Lifecycle hooks can be used inside composables because composables run in the component setup context.

Why it matters: Not knowing this limits how you organize side effects and setup logic, making code less reusable.

Quick: Is it safe to return reactive objects directly from composables without restrictions? Commit to yes or no.

Common Belief: Returning reactive objects directly from composables is always safe and recommended.

Reality: Returning reactive objects directly can expose internal state to unwanted mutations; sometimes readonly wrappers are needed.

Why it matters: Ignoring this can cause hard-to-debug bugs from accidental state changes outside the composable.

Quick: Do composables have to start with 'use'? Commit to yes or no.

Common Belief: The 'use' prefix is mandatory for all composables.

Reality: The 'use' prefix is a strong convention but not enforced by Vue; it helps identify composables clearly.

Why it matters: Not following conventions can confuse team members and reduce code readability.

Expert Zone

1

Composables can return computed properties to expose derived state that updates automatically.

2

You can combine multiple composables inside one to build complex reusable logic layers.

3

Using provide/inject inside composables allows sharing reactive data deeply without prop drilling.

When NOT to use

Avoid using composables for very simple or one-off logic that doesn't need reuse; in those cases, keep logic inside the component setup. Also, for global state management, consider Vuex or Pinia instead of relying solely on shared composables.

Production Patterns

In real apps, composables are organized into folders by feature or domain. Teams create libraries of composables for common tasks like form handling, API calls, or animations. They also write tests specifically for composables to ensure logic correctness independent of UI.

Connections

React Hooks

Similar pattern of extracting reusable logic into functions that manage state and side effects.

Understanding composables helps grasp React Hooks because both solve the same problem of code reuse in UI frameworks.

Modular Programming

Composables build on the idea of breaking code into small, reusable modules.

Knowing modular programming principles clarifies why composables improve maintainability and testability.

Factory Functions in JavaScript

Composables are like factory functions that create and return objects with state and behavior.

Recognizing composables as factory functions helps understand their flexibility and how they encapsulate logic.

Common Pitfalls

#1 Sharing state unintentionally by defining reactive variables inside composables expecting isolation.

Wrong approach:

let count = ref(0);
function useCounter() {
return { count };
}
// All components share the same count, causing bugs.

Correct approach:

function useCounter() {
const count = ref(0);
return { count };
}
// Each component gets its own count state.

Root cause:

Misunderstanding where reactive state is created leads to shared state bugs.

#2 Mutating reactive state returned from composables directly when it should be read-only.

Wrong approach:

const { count } = useSafeCounter();
count.value = 10; // Allowed but breaks encapsulation

Correct approach:

const { count } = useSafeCounter();
// count is readonly, so mutation is prevented
// Use provided methods to change state instead

Root cause:

Not protecting internal state leads to accidental external mutations.

#3 Using lifecycle hooks outside of setup context causing errors.

Wrong approach:

function useLogger() {
onMounted(() => console.log('Hi'));
}
useLogger(); // Called outside setup, causes error

Correct approach:

function useLogger() {
onMounted(() => console.log('Hi'));
}
// Call useLogger() only inside component setup()

Root cause:

Lifecycle hooks require a component setup context to work.

Key Takeaways

Custom composables are simple functions that bundle reactive state and logic for reuse across Vue components.

They rely on Vue's Composition API tools like ref, reactive, and lifecycle hooks to work.

Each call to a composable creates new state unless you explicitly share it outside the function.

Composables can accept parameters and return readonly or computed values to control usage and protect state.

Using composables improves code organization, reduces duplication, and makes apps easier to maintain and test.