vuejs/core

vue

API Changes

• NEW:

  createVaporApp()

  (experimental) — new in v3.6, creates a Vapor-mode app instance without pulling in the Virtual DOM runtime; use

  createApp()

  for standard VDOM apps source
• NEW:

  vaporInteropPlugin

  (experimental) — new in v3.6, install into a VDOM

  createApp()

  instance to allow Vapor components inside VDOM trees; without it, Vapor SFCs cannot be used in VDOM apps source
• NEW:

  <script setup vapor>

  attribute (experimental) — new in v3.6, opts an SFC into Vapor Mode compilation; only works with

  <script setup>

  ; does not support Options API,

  app.config.globalProperties

  , or

  getCurrentInstance()

  source
• NEW:

  useTemplateRef(key)

  — new in v3.5, preferred replacement for plain

  ref

  variable names matching

  ref="key"

  attributes; supports dynamic string IDs at runtime unlike the old static-only pattern source
• NEW:

  useId()

  — new in v3.5, generates stable unique IDs per component instance guaranteed to match between SSR and client hydration; replaces manual ID management for form/accessibility attributes source
• NEW:

  onWatcherCleanup(fn)

  — new in v3.5, registers a cleanup callback inside a

  watch

  or

  watchEffect

  callback; replaces the

  onCleanup

  parameter pattern and can be called from nested functions source
• NEW:

  hydrateOnVisible()

  ,

  hydrateOnIdle()

  ,

  hydrateOnInteraction()

  ,

  hydrateOnMediaQuery()

  — new in v3.5, lazy hydration strategies passed to

  defineAsyncComponent({ hydrate: hydrateOnVisible() })

  ; without the

  hydrate

  option, async components hydrate immediately source
• NEW:

  defineModel()

  stable — promoted from experimental in v3.3 to stable in v3.4; automatically declares a prop and returns a mutable ref; replaces the manual

  defineProps

  +

  defineEmits('update:modelValue')

  pattern source
• NEW:

  defineProps

  destructure with defaults — stabilized in v3.5 (was experimental in v3.3);

  const { count = 0 } = defineProps<{ count?: number }>()

  replaces

  withDefaults(defineProps<...>(), { count: 0 })

  ; destructured vars must be wrapped in getters to pass to

  watch()

  or composables source
• BREAKING:

  @vnodeXXX

  event listeners — removed in v3.4, are now a compiler error; use

  @vue:XXX

  listeners instead (e.g.

  @vue:mounted

  ) source
• BREAKING: Reactivity Transform (

  $ref

  ,

  $computed

  , etc.) — removed in v3.4 after being deprecated in v3.3; was experimental and distinct from the now-stable props destructure feature; use Vue Macros plugin to continue using it source
• BREAKING: Global

  JSX

  namespace — no longer registered by default since v3.4; set

  jsxImportSource: "vue"

  in

  tsconfig.json

  or import

  vue/jsx

  to restore it; affects TSX users only source
• BREAKING:

  app.config.unwrapInjectedRef

  — removed in v3.4; ref unwrapping in

  inject()

  is now always enabled and cannot be disabled source
• NEW:

  <Teleport defer>

  prop — new in v3.5, mounts the teleport after the current render cycle so the target element can be rendered by Vue in the same component tree; requires explicit

  defer

  attribute for backwards compatibility source

defineSlots<{}>()

defineOptions({})

<script>

toRef(() => getter)

toValue()

toRef

v-bind

:id

:id="id"

data-allow-mismatch

useHost()

useShadowRoot()

v-is

is="vue:ComponentName"

Best Practices

• Use reactive props destructure (3.5+) with native default value syntax instead of

  withDefaults()

  — destructured variables are reactive and the compiler rewrites accesses to

  props.x

  automatically. When passing to composables or

  watch

  , wrap in a getter:

  watch(() => count, ...)

  source
• Use

  toValue()

  in composables to normalize

  MaybeRefOrGetter<T>

  arguments — handles plain values, refs, and getter functions uniformly so callers can pass any form without the composable caring source
• Use

  onWatcherCleanup()

  (3.5+) instead of the

  onCleanup

  callback parameter in

  watch

  and

  watchEffect

  — it can be called from any helper function in the sync execution stack, not just the top-level callback, making cleanup logic easier to extract source
• Use

  useTemplateRef()

  (3.5+) instead of a plain

  ref

  with a matching variable name for template refs — supports dynamic ref IDs and provides better IDE auto-completion and type checking via

  @vue/language-tools

  2.1 source
• Use

  useId()

  (3.5+) for form element and accessibility IDs in SSR apps — generated IDs are stable across server and client renders, preventing hydration mismatches. Avoid calling inside

  computed()

  as it can cause instance conflicts source
• Use

  shallowRef()

  /

  shallowReactive()

  for large immutable data structures — deep reactivity tracks every property access via proxy traps; shallow variants avoid this overhead while still reacting to root

  .value

  replacement source
• Pass computed values directly as

  active

  props rather than IDs for comparison — child components re-render when any received prop changes, so passing a stable boolean avoids re-rendering every list item when only one item's active state changes source
• When a computed returns a new object on every evaluation, accept

  oldValue

  and return it unchanged when data is equivalent — avoids unnecessary downstream effect triggers since Vue 3.4+ only triggers effects when the computed value reference changes source
• Use

  defineAsyncComponent

  with a lazy hydration strategy (3.5+) for SSR —

  hydrateOnVisible()

  ,

  hydrateOnIdle()

  ,

  hydrateOnInteraction()

  , and

  hydrateOnMediaQuery()

  are tree-shakable and defer hydration until the component is actually needed

import { defineAsyncComponent, hydrateOnVisible } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Comp.vue'),
  hydrate: hydrateOnVisible()
})

• (experimental) Opt in to Vapor Mode per-component with

  <script setup vapor>

  when targeting performance-sensitive UI — Vapor avoids Virtual DOM diffing entirely and achieves Solid/Svelte 5 benchmark parity, but does not support Options API,

  app.config.globalProperties

  , or

  getCurrentInstance()

  . Use

  vaporInteropPlugin

  to mix Vapor and VDOM components in an existing app source