Vue Options API → Composition API

The incremental model

The Composition API does not replace the Options API — Vue 3 supports both, even within the same project. That means there is no cutover: you can convert a single component to <script setup>, extract shared logic into composables, and leave the rest on the Options API. Adopt it where logic reuse or TypeScript inference is painful, and leave simple components alone.

Component conversion

<!-- Options API -->
<script>
export default {
  data() {
    return { count: 0 }
  },
  computed: {
    double() {
      return this.count * 2
    },
  },
  mounted() {
    console.log('mounted')
  },
}
</script>

<!-- Composition API with <script setup> -->
<script setup>
import { ref, computed, onMounted } from 'vue'
const count = ref(0)
const double = computed(() => count.value * 2)
onMounted(() => console.log('mounted'))
</script>

When the pattern applies

• Components with logic you want to share across files (extract a composable instead of a mixin).
• Components where TypeScript inference under the Options API is awkward.
• Components you are already touching for the Vue 3 upgrade.

Composables vs mixins

• Mixins merge implicitly and clash on naming; composables are explicit imports with clear return values.
• A composable is a plain `use*()` function that calls ref/reactive/computed/watch and returns reactive state.
• Prefer composables for new shared logic; convert mixins to composables as you touch the components that use them.

Edge cases

• Reactivity loss: destructuring a reactive() object breaks reactivity — use toRefs.
• `this` no longer exists in <script setup>; replace it with the local refs and helpers.
• Two-way mixin state rarely maps cleanly — model it explicitly in the composable's return value.
• Template refs and provide/inject replace patterns that previously reached through component internals.

Conversion checklist

• ☐data/computed/watch mapped to ref/reactive/computed/watch
• ☐Lifecycle methods mapped to on* hooks
• ☐Mixins extracted into composables where shared logic exists
• ☐Template and public props/emits unchanged
• ☐Component tests still pass after conversion

Related paths

• Upgrade to Vue 3high risk
  Next step forward
• Vue 2 to Vue 3 Migration Guidehigh risk
  Related path
• Fix Vue 3 Migration Errorsmedium risk
  Next step forward

Official sources

• Official docsVue.js Guidevuejs.orgreliability 98%

  Backs the breaking-change and migration-step claims.

• Migration guideVue 3 Migration Guidevuejs.orgreliability 98%

  Backs the breaking-change and migration-step claims.