/vue-debug-guides

Use shallowRef for Dynamic Component References

Impact: MEDIUM - When storing Vue components in reactive state for dynamic rendering, using ref() or reactive() causes Vue warnings and unnecessary reactivity overhead. Use shallowRef() instead.

Task Checklist

• Use shallowRef for storing component references
• Use markRaw when storing components in reactive objects
• Avoid wrapping component definitions with deep reactivity
• Check console for "[Vue warn]: Vue received a Component that was made a reactive object"

The Problem

Vue components are objects with internal properties that should not be made reactive. When you store a component in ref() or reactive(), Vue traverses all properties deeply, which:

1. Triggers a console warning
2. Creates unnecessary reactive proxies
3. Can cause subtle bugs with component identity
4. Impacts performance

Incorrect - Using ref() for components:

import { ref } from 'vue'
import ComponentA from './ComponentA.vue'
import ComponentB from './ComponentB.vue'

// BAD: Vue will warn about making component reactive
const currentComponent = ref(ComponentA)

function switchComponent() {
  currentComponent.value = ComponentB
}

Console warning:

[Vue warn]: Vue received a Component that was made a reactive object.
This can lead to unnecessary performance overhead and should be avoided
by marking the component with `markRaw` or using `shallowRef` instead of `ref`.

Solution 1: Use shallowRef

shallowRef only makes the .value reference reactive, not the contents:

import { shallowRef, type Component } from 'vue'
import ComponentA from './ComponentA.vue'
import ComponentB from './ComponentB.vue'

// CORRECT: shallowRef doesn't deep-proxy the component
const currentComponent = shallowRef<Component>(ComponentA)

function switchComponent() {
  currentComponent.value = ComponentB
}

<template>
  <component :is="currentComponent" />
</template>

Solution 2: Use markRaw in Reactive Objects

When components are part of a larger reactive object:

import { reactive, markRaw, type Component } from 'vue'
import TabHome from './TabHome.vue'
import TabProfile from './TabProfile.vue'
import TabSettings from './TabSettings.vue'

interface Tab {
  name: string
  component: Component
}

// CORRECT: markRaw prevents reactivity on component objects
const tabs = reactive<Tab[]>([
  { name: 'Home', component: markRaw(TabHome) },
  { name: 'Profile', component: markRaw(TabProfile) },
  { name: 'Settings', component: markRaw(TabSettings) }
])

const activeTab = shallowRef<Tab>(tabs[0])

<template>
  <div class="tabs">
    <button
      v-for="tab in tabs"
      :key="tab.name"
      @click="activeTab = tab"
    >
      {{ tab.name }}
    </button>
  </div>
  <component :is="activeTab.component" />
</template>

TypeScript Typing

For proper TypeScript support with dynamic components:

import { shallowRef, type Component, type DefineComponent } from 'vue'

// Generic component type
const currentComponent = shallowRef<Component | null>(null)

// Or more specific with props
interface MyComponentProps {
  title: string
}

const currentComponent = shallowRef<DefineComponent<MyComponentProps> | null>(null)

Dynamic Import with shallowRef

When using dynamic imports for code splitting:

import { shallowRef, defineAsyncComponent, type Component } from 'vue'

const currentComponent = shallowRef<Component | null>(null)

async function loadComponent(name: string) {
  const component = defineAsyncComponent(
    () => import(`./components/${name}.vue`)
  )
  currentComponent.value = component
}

Component Registry Pattern

For tab systems or wizard-like interfaces:

import { shallowRef, markRaw, type Component } from 'vue'

// Type-safe component registry
const componentRegistry = {
  home: markRaw(defineAsyncComponent(() => import('./Home.vue'))),
  about: markRaw(defineAsyncComponent(() => import('./About.vue'))),
  contact: markRaw(defineAsyncComponent(() => import('./Contact.vue')))
} as const

type ComponentKey = keyof typeof componentRegistry

const currentView = shallowRef<ComponentKey>('home')

// Computed to get current component
const currentComponent = computed(() => componentRegistry[currentView.value])

<template>
  <component :is="currentComponent" />
</template>

When to Use Each Approach

Common Mistakes

Mistake 1: Using computed with ref

// BAD: Still triggers warning
const components = ref([ComponentA, ComponentB])
const current = computed(() => components.value[index.value])

// GOOD: Use shallowRef for the array
const components = shallowRef([ComponentA, ComponentB])

Mistake 2: Forgetting markRaw in map

// BAD: Components in map become reactive
const routes = reactive(new Map([
  ['home', HomeComponent],
  ['about', AboutComponent]
]))

// GOOD: Mark each component as raw
const routes = reactive(new Map([
  ['home', markRaw(HomeComponent)],
  ['about', markRaw(AboutComponent)]
]))

Reference

• Vue.js Reactivity in Depth - Reducing Reactivity Overhead
• Vue.js API - shallowRef
• Vue.js API - markRaw