Utility Types {#utility-types}

:::info This page only lists a few commonly used utility types that may need explanation for their usage. For a full list of exported types, consult the source code. :::

PropType<T> {#proptype-t}

Used to annotate a prop with more advanced types when using runtime props declarations.

Example

import type { PropType } from 'vue'

interface Book {
  title: string
  author: string
  year: number
}

export default {
  props: {
    book: {
      // provide more specific type to `Object`
      type: Object as PropType<Book>,
      required: true
    }
  }
}

See also Guide - Typing Component Props

MaybeRef<T> {#mayberef}

Alias for T | Ref<T>. Useful for annotating arguments of Composables.

Only supported in 3.3+.

MaybeRefOrGetter<T> {#maybereforgetter}

Alias for T | Ref<T> | (() => T). Useful for annotating arguments of Composables.

Only supported in 3.3+.

ExtractPropTypes<T> {#extractproptypes}

Extract prop types from a runtime props options object. The extracted types are internal facing - i.e. the resolved props received by the component. This means boolean props and props with default values are always defined, even if they are not required.

To extract public facing props, i.e. props that the parent is allowed to pass, use ExtractPublicPropTypes.

Example

const propsOptions = {
  foo: String,
  bar: Boolean,
  baz: {
    type: Number,
    required: true
  },
  qux: {
    type: Number,
    default: 1
  }
} as const

type Props = ExtractPropTypes<typeof propsOptions>
// {
//   foo?: string,
//   bar: boolean,
//   baz: number,
//   qux: number
// }

ExtractPublicPropTypes<T> {#extractpublicproptypes}

Extract prop types from a runtime props options object. The extracted types are public facing - i.e. the props that the parent is allowed to pass.

Example

const propsOptions = {
  foo: String,
  bar: Boolean,
  baz: {
    type: Number,
    required: true
  },
  qux: {
    type: Number,
    default: 1
  }
} as const

type Props = ExtractPublicPropTypes<typeof propsOptions>
// {
//   foo?: string,
//   bar?: boolean,
//   baz: number,
//   qux?: number
// }

ComponentInstance {#componentinstance}

Used to extract the instance type of a component (equivalent to the type of this in its options).

Example

<script setup lang="ts">
import { ComponentInstance } from 'vue'
import Foo from './Foo.vue'

const fooEl = ref<null | ComponentInstance<typeof Foo>>(null)
</script>
<template>
  <Foo ref="fooEl" />
</template>

ComponentCustomProperties {#componentcustomproperties}

Used to augment the component instance type to support custom global properties.

Example

import axios from 'axios'

declare module 'vue' {
  interface ComponentCustomProperties {
    $http: typeof axios
    $translate: (key: string) => string
  }
}

:::tip Augmentations must be placed in a module .ts or .d.ts file. See Type Augmentation Placement for more details. :::

See also Guide - Augmenting Global Properties

ComponentCustomOptions {#componentcustomoptions}

Used to augment the component options type to support custom options.

Example

import { Route } from 'vue-router'

declare module 'vue' {
  interface ComponentCustomOptions {
    beforeRouteEnter?(to: any, from: any, next: () => void): void
  }
}

:::tip Augmentations must be placed in a module .ts or .d.ts file. See Type Augmentation Placement for more details. :::

See also Guide - Augmenting Custom Options

ComponentCustomProps {#componentcustomprops}

Used to augment allowed TSX props in order to use non-declared props on TSX elements.

Example

declare module 'vue' {
  interface ComponentCustomProps {
    hello?: string
  }
}

export {}

// now works even if hello is not a declared prop
<MyComponent hello="world" />

:::tip Augmentations must be placed in a module .ts or .d.ts file. See Type Augmentation Placement for more details. :::

CSSProperties {#cssproperties}

Used to augment allowed values in style property bindings.

Example

Allow any custom CSS property

declare module 'vue' {
  interface CSSProperties {
    [key: `--${string}`]: string
  }
}

<div style={ { '--bg-color': 'blue' } }>

<div :style="{ '--bg-color': 'blue' }"></div>

:::tip Augmentations must be placed in a module .ts or .d.ts file. See Type Augmentation Placement for more details. :::

:::info See also SFC <style> tags support linking CSS values to dynamic component state using the v-bind CSS function. This allows for custom properties without type augmentation.

v-bind() in CSS :::

DeclareComponent {#declarecomponent}

More user friendly way to generate or extend DefineComponent type.

:::warning Note that you must define the properties, using DeclareComponent is just typescript, it will fail at runtime. :::

Validator Example

type Validator<T> = { value: T; validate(): boolean }
declare function generateComponent<
  T extends Record<string, Validator<any>>
>(schema: T): DeclareComponent<{ [K in keyof T]: T[K]['value'] }>

generateComponent({
  test: {
    value: 'test',
    validate: () => true
  }
}).props.test // { type: String, required: true}

HoC Example

declare function extendAsHTMLElement<T extends DefineComponent>(
  options: T
): T & DeclareComponent<HTMLAttributes>

extendAsHTMLElement(
  defineComponent({
    setup:
      (_, { attrs }) =>
      () =>
        h('input', attrs)
  })
).props.about // { type: String, required: false}

Generic Example

You don't necessarily need to you DeclareComponent, but you can.

Is necessary to use new<...>{ $props: { ... } } for Generic components, using type helpers with Generic params might break generic types.

type ErrorLevel = 'debug' | 'warning' | 'error'

declare function ErrorComponent<T>(options: T): T &
    new <T extends ErrorLevel = 'debug'>(): {
      $props: { type: T } & {
        [K in `on${Capitalize<T>}`]: (msg: string) => void
      }
      $slots: SlotsType<Record<T, (msg: string) => any[]>>
    }

const Comp = ErrorComponent(
  defineComponent({
    props: {
      type: {
        type: String as () => ErrorLevel,
        default: 'debug'
      }
    },
    emits: ['debug', 'warning', 'error']
  })
)
;<Comp type="debug" onDebug={() => {}} />
// @ts-expect-error onError is not there
;<Comp type="debug" onError={(v) => {}} />

ExtractComponentOptions<T> {#extractcomponentoptions}

Extracts component declared options.

const Comp = defineComponent({
  props: {
    foo: String
  }
})
const options = {} as ExtractComponentOptions<typeof Comp>
options.props // { foo: StringConstructor }

ExtractComponentPropOptions<T> {#extractcomponentpropoptions}

Extracts the component props as the component was created, or the props from the ComponentPublicInstance.

const Comp = defineComponent({
  props: {
    foo: String
  }
})
const props = {} as ExtractComponentPropOptions<typeof Comp>
props.foo // StringConstructor

ExtractComponentSlotOptions<T> {#extractcomponentslotoptions}

Extracts the component slots as the component was created.

const Comp = defineComponent({
  slots: {} as SlotsType<{
    foo: (bar: string) => any
    baz: (bar: number) => any
  }>
})
const slots = {} as ExtractComponentSlotOptions<typeof Comp>
slots // SlotsType<{ foo: (bar: string) => any; baz: (bar: number) => any; }>

ExtractComponentEmitOptions<T> {#extractcomponentemitoptions}

Extracts the component emits as the component was created.

const Comp = defineComponent({
  emits: {
    foo: (test: string) => true
  }
})
const emits = {} as ExtractComponentEmitOptions<typeof Comp>
emits.foo // (test: string) => true

ObjectToComponentProps<T> {#objecttocomponentprops}

Converts an Record<string, any> into a props definition like object.

Useful for extending component props.

const props: ObjectToComponentProps<{ foo: 'bar' | 'baz', baz?: number }>
 // props is:
 {
   foo: {
    type: Prop<'bar' | 'baz'>,
    required: true
   },
   baz: {
    type: Prop<number>,
    required: false
   }
 }

ComponentEmitsAsProps<T> {#componentemitsasprops}

Converts Emit declaration into props declaration, returned object will be optional.

declare const emit: ComponentEmitsAsProps<{ emits: { foo: () => true } }>
emit.onFoo?.() // ok

ComponentProps<T> {#componentprops}

Returns runtime props for a component.

const Comp = defineComponent({
  props: {
    foo: String
  }
})
const props = {} as ComponentProps<typeof Comp>
props.foo // string | undefined

ComponentSlots<T> {#componentslots}

Returns runtime slots for a component.

const Comp = defineComponent({
  slots: {} as SlotsType<{
    default: (arg: { msg: string }) => any
  }>
})

const slots = {} as ComponentSlots<typeof Comp>
slots.default // { arg: { msg: string } } => any

ComponentEmit<T> {#componentemit}

Returns the emit function from options.

const CompSlotsTyped = defineComponent({
  emits: {
    foo: (arg: string) => true
  }
})

const emit = {} as ComponentEmit<typeof CompSlotsTyped>
emit // (event: 'foo', arg: string) => void

ComponentData<T> {#componentdata}

Returns the component bindings from data and setup.

const Comp = defineComponent({
  data() {
    return {
      foo: 'string'
    }
  },

  setup(props, ctx) {
    return {
      bar: 42
    }
  }
})

const data = {} as ComponentData<typeof Comp>
data.foo // string
data.bar // number

DefineComponentOptions & DefineComponentFromOptions {#definecomponentoptions}

Allows to get vue component options and generate DefineComponent type.

:::warning The generic order is not prone to change, but it might, Options should be the last generic used, new generics will be added before Options. :::

:::info Note that you if you need to handle generics, it should be it's own overload, since any change to the Generic definition might break the Generic type. :::

declare function defineComponentWithDefaults<
  Props = never,
  RawBindings = {},
  D = {},
  C extends ComputedOptions = {},
  M extends MethodOptions = {},
  Mixin extends ComponentOptionsMixin = ComponentOptionsMixin,
  Extends extends ComponentOptionsMixin = ComponentOptionsMixin,
  E extends EmitsOptions = {},
  EE extends string = string,
  I extends ComponentInjectOptions = {},
  II extends string = string,
  S extends SlotsType = {},
  Options extends {} = {}
>(
  options: DefineComponentOptions<
    Props,
    RawBindings,
    D,
    C,
    M,
    Mixin,
    Extends,
    E,
    EE,
    I,
    II,
    S,
    Options
  >,
  defaults: Partial<
    [Props] extends [string]
      ? { [K in Props]?: any }
      : ExtractPropTypes<Props>
  >
): DefineComponentFromOptions<
  undefined extends Props ? {} : Props,
  RawBindings,
  D,
  C,
  M,
  Mixin,
  Extends,
  E,
  EE,
  I,
  II,
  S,
  Options
>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

utility-types.md

utility-types.md

Utility Types {#utility-types}

PropType<T> {#proptype-t}

MaybeRef<T> {#mayberef}

MaybeRefOrGetter<T> {#maybereforgetter}

ExtractPropTypes<T> {#extractproptypes}

ExtractPublicPropTypes<T> {#extractpublicproptypes}

ComponentInstance {#componentinstance}

ComponentCustomProperties {#componentcustomproperties}

ComponentCustomOptions {#componentcustomoptions}

ComponentCustomProps {#componentcustomprops}

CSSProperties {#cssproperties}

DeclareComponent {#declarecomponent}

ExtractComponentOptions<T> {#extractcomponentoptions}

ExtractComponentPropOptions<T> {#extractcomponentpropoptions}

ExtractComponentSlotOptions<T> {#extractcomponentslotoptions}

ExtractComponentEmitOptions<T> {#extractcomponentemitoptions}

ObjectToComponentProps<T> {#objecttocomponentprops}

ComponentEmitsAsProps<T> {#componentemitsasprops}

ComponentProps<T> {#componentprops}

ComponentSlots<T> {#componentslots}

ComponentEmit<T> {#componentemit}

ComponentData<T> {#componentdata}

DefineComponentOptions & DefineComponentFromOptions {#definecomponentoptions}

Files

utility-types.md

Latest commit

History

utility-types.md

File metadata and controls

Utility Types {#utility-types}

PropType<T> {#proptype-t}

MaybeRef<T> {#mayberef}

MaybeRefOrGetter<T> {#maybereforgetter}

ExtractPropTypes<T> {#extractproptypes}

ExtractPublicPropTypes<T> {#extractpublicproptypes}

ComponentInstance {#componentinstance}

ComponentCustomProperties {#componentcustomproperties}

ComponentCustomOptions {#componentcustomoptions}

ComponentCustomProps {#componentcustomprops}

CSSProperties {#cssproperties}

DeclareComponent {#declarecomponent}

ExtractComponentOptions<T> {#extractcomponentoptions}

ExtractComponentPropOptions<T> {#extractcomponentpropoptions}

ExtractComponentSlotOptions<T> {#extractcomponentslotoptions}

ExtractComponentEmitOptions<T> {#extractcomponentemitoptions}

ObjectToComponentProps<T> {#objecttocomponentprops}

ComponentEmitsAsProps<T> {#componentemitsasprops}

ComponentProps<T> {#componentprops}

ComponentSlots<T> {#componentslots}

ComponentEmit<T> {#componentemit}

ComponentData<T> {#componentdata}

DefineComponentOptions & DefineComponentFromOptions {#definecomponentoptions}