• Start Date: 2025-08-27
• Target Major Version: 3.x
• Reference Issues:
• Implementation PR:

Summary

Introduce a concise way to define local/micro components within another component file, without requiring JSX/TSX.

Basic example

Doesn't have to be exactly this, this is just a general idea of how it could be:

const MyButton = defineLocalComponent(({ props, emit }) =>
  <template>
    <button @click="emit('click')">{{ props.count }}</button>
  </template>
)

Motivation

Developers often encounter “micro-components” - Template code that are:

• Too small to create their own .vue file.
• Reusable enough that duplication feels wrong.

Currently the only way to achieve this is using JSX and h() calls

• But, JSX, h() calls are verbose and difficult to read.
• Also, JSX requires extra tooling that some teams avoid.

Detailed design

Here is an example of a practical use case of this feature. Let us assume we are creating a button with inline icon:

<template>
  <div>
    <button class="icon-btn" @click="() => {}">
      <i class="fa fa-plus"></i>
      Add
    </button>

    <button class="icon-btn" @click="() => {}">
      <i class="fa fa-trash"></i>
      Delete
    </button>
  </div>
</template>

In this example, most of the code is duplicate but also:

• Too small to create their own .vue file.
• Reusable enough that duplication feels wrong.

This problem could be solved by defining micro-component locally within the file. The code would then look something like this:

<script setup>
const IconButton = defineLocalComponent(({ props, emit }) =>
  <button @click="emit('click')" class="icon-btn">
    <i :class="props.icon"></i>
    {{ props.label }}
  </button>
)
</script>

<template>
  <div>
    <IconButton icon="fa fa-plus" label="Add" @click="() => {}" />
    <IconButton icon="fa fa-trash" label="Delete" @click="() => {}" />
  </div>
</template>

Drawbacks

• Requires compiler level changes that works for build-time as well as run-time

Alternatives

JSX and h() calls.

• But, JSX, h() calls are verbose and difficult to read.
• Also, JSX requires extra tooling that some teams avoid.

Adoption strategy

There will be no breaking changes. Developers can adopt to new or existing Vue 3 codebase without breaking anything.

Unresolved questions

• Should the local components only support props and emits?