TypeScript with Composition API | Vue.js

Creating an Application
Reactivity Fundamentals
Class and Style Bindings
Conditional Rendering
Fallthrough Attributes
Single-File Components
Server-Side Rendering (SSR)
Production Deployment
TS with Composition API
Render Functions & JSX
Vue and Web Components
Animation Techniques
This page assumes you've already read the overview on Using Vue with TypeScript.
When using <script setup>, the defineProps() macro supports inferring the props types based on its argument:
This is called "runtime declaration", because the argument passed to defineProps() will be used as the runtime props option.
However, it is usually more straightforward to define props with pure types via a generic type argument:
This is called "type-based declaration". The compiler will try to do its best to infer the equivalent runtime options based on the type argument. In this case, our second example compiles into the exact same runtime options as the first example.
You can use either type-based declaration OR runtime declaration, but you cannot use both at the same time.
We can also move the props types into a separate interface:
This also works if Props is imported from another file such as a relative import, a path alias (e.g., @/types), or an external dependency (e.g., node_modules). This feature requires TypeScript to be a peer dependency of Vue.
In version 3.2 and below, the generic type parameter for defineProps() were limited to a type literal or a reference to a local interface.
This limitation was resolved in 3.3. The latest version of Vue supports referencing imported and a limited set of complex types in the type parameter position. However, because the type to runtime conversion is still AST-based, some complex types that require actual type analysis, e.g. conditional types, are not supported. You can use conditional types for the type of a single prop, but not the entire props object.
When using type-based declaration, we lose the ability to declare default values for the props. This can be resolved by using Reactive Props Destructure :
In 3.4 and below, Reactive Props Destructure is not enabled by default. An alternative is to use the withDefaults compiler macro:
This will be compiled to equivalent runtime props default options. In addition, the withDefaults helper provides type checks for the default values, and ensures the returned props type has the optional flags removed for properties that do have default values declared.
Note that default values for mutable reference types (like arrays or objects) should be wrapped in functions when using withDefaults to avoid accidental modification and external side effects. This ensures each component instance gets its own copy of the default value. This is not necessary when using default values with destructure.
If not using <script setup>, it is necessary to use defineComponent() to enable props type inference. The type of the props object passed to setup() is inferred from the props option.
With type-based declaration, a prop can use a complex type much like any other type:
For runtime declaration, we can use the PropType utility type:
This works in much the same way if we're specifying the props option directly:
The props option is more commonly used with the Options API, so you'll find more detailed examples in the guide to TypeScript with Options API. The techniques shown in those examples also apply to runtime declarations using defineProps().
In <script setup>, the emit function can also be typed using either runtime declaration OR type declaration:
The type argument can be one of the following:
As we can see, the type declaration gives us much finer-grained control over the type constraints of emitted events.
When not using <script setup>, defineComponent() is able to infer the allowed events for the emit function exposed on the setup context:
Refs infer the type from the initial value:
Sometimes we may need to specify complex types for a ref's inner value. We can do that by using the Ref type:
Or, by passing a generic argument when calling ref() to override the default inference:
If you specify a generic type argument but omit the initial value, the resulting type will be a union type that includes undefined:
reactive() also implicitly infers the type from its argument: