Lightweight TypeScript-first Vue prop type definitions
import { defineComponent } from 'vue'; import { arrayProp, booleanProp, functionProp, isPositive, numberProp, oneOfProp, stringProp, } from 'vue-ts-types'; defineComponent({ props: { disabled: booleanProp().withDefault(false), // resulting prop type: boolean title: stringProp().optional, // resulting prop type: string | undefined description: stringProp().nullable, // resulting prop type: string | null items: arrayProp<string>().required, // resulting prop type: string[] callback: functionProp<() => void>().optional, // resulting prop type: (() => void) | undefined color: oneOfProp(['red', 'green', 'blue'] as const).withDefault('red'), // resulting prop type: 'red' | 'green' | 'blue' timeout: numberProp(isPositive).required, // resulting prop type: number }, });Prop declarations are verbose
Declaring props is quite verbose, especially if you are using TypeScript and want to annotate more complex types (with PropType).
options: { type: Object as PropType<Options>, required: true, } // with vue-ts-types: options: objectProp<Options>().requiredAnnotating optional complex props is error-prone
It's easy to forget using a union type with undefined or null when the prop is not required.
options: { type: Object as PropType<Options>, // wrong, it should be `Options | undefined` required: false, } // with vue-ts-types: options: objectProp<Options>().optional // automatically typed as `Options | undefined`Specifying both default and required can be contradictory
By specifying a prop's default value, the prop is automatically optional, even when required is set to true. See also the vue/no-required-prop-with-default ESLint rule.
disabled: { type: Boolean, required: true, default: false, // contradictory to `required: true` } // with vue-ts-types: disabled: booleanProp().required // either required without default disabled: booleanProp().withDefault(false) // or optional with defaultCustom validation errors are not helpful
Since prop validators return only a boolean validation result, the reason why a value failed to validate is not printed in the console error.
age: { type: Number, required: true, validator: (age: unknown) => { return typeof age === 'number' && Number.isInteger(age) && age >= 18 }, } // with vue-ts-types: age: integerProp((age: unknown) => { if (typeof age !== 'number' || age < 18) { return 'age should be a number of at least 18' } return undefined }).requirednpm install vue-ts-typesvue-ts-types has no dependencies and is tested to be compatible with Vue.js v2.6, v2.7 and v3.2.
Each of the prop functions returns an object with the following properties:
.optional: Use this to mark the prop as not required with a default value ofundefined. Also includesundefinedin the resulting prop type..nullable: Use this to mark the prop as not required with a default value ofnull. Also includesnullin the resulting prop type..required: Use this to mark the prop as required without a default value..withDefault(value): Use this to set a default value for the prop. Note that the value has to fit the prop type. For non-primitive types, the value has to be a function that returns the default value.
ℹ️ Note:
Due to the way Vue props work, a prop's default value will only be used when passingundefined, not fornull.
See issue #3135 in vuejs/vue.
Custom validator functions can be passed to any of the prop types. They are called with the value of the prop (type unknown) and should return a validation error message, or undefined if the value is valid. Validator functions do not influence type inference.
import { numberProp } from 'vue-ts-types'; type Validator = (value: unknown) => string | undefined; const isPositive: Validator = (value) => { if (typeof value !== 'number' || value <= 0 || Number.isNaN(value)) { return 'value should be a positive number'; } return undefined; }; numberProp(isPositive).optional; // → prop type: number | undefinedFor convenience, some common validator functions are included in the library and can be imported just like prop types:
isNegative: only allows negative numbers (< 0)isPositive: only allows positive numbers (> 0)isNonNegative: only allows non-negative numbers (>= 0)isNonPositive: only allows non-positive numbers (<= 0)
Allows any string. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type at compile time with a union type. (Consider using oneOfProp in this case.)
stringProp().optional; // → prop type: string | undefined stringProp().nullable; // → prop type: string | null stringProp().required; // → prop type: string stringProp().withDefault('foo'); // → prop type: string type Foo = 'a' | 'b' | 'c'; stringProp<Foo>().optional; // → prop type: Foo | undefined stringProp<Foo>().nullable; // → prop type: Foo | null stringProp<Foo>().required; // → prop type: Foo stringProp<Foo>().withDefault('a'); // → prop type: FooAllows any boolean (validated at runtime and compile time).
booleanProp().optional; // → prop type: boolean | undefined booleanProp().nullable; // → prop type: boolean | null booleanProp().required; // → prop type: boolean booleanProp().withDefault(false); // → prop type: booleanAllows any number (validated at runtime and compile time). Type parameter T can be used to restrict the type at compile time with a union type. (Consider using oneOfProp in this case.)
numberProp().optional; // → prop type: number | undefined numberProp().nullable; // → prop type: number | null numberProp().required; // → prop type: number numberProp().withDefault(3.1415); // → prop type: number type Foo = 1 | 2 | 3; numberProp<Foo>().optional; // → prop type: Foo | undefined numberProp<Foo>().nullable; // → prop type: Foo | null numberProp<Foo>().required; // → prop type: Foo numberProp<Foo>().withDefault(1); // → prop type: FooAllows any integer (validated at runtime).
integerProp().optional; // → prop type: number | undefined integerProp().nullable; // → prop type: number | null integerProp().required; // → prop type: number integerProp().withDefault(42); // → prop type: numberAllows any Date object (validated at runtime and compile time).
dateProp().optional; // → prop type: Date | undefined dateProp().nullable; // → prop type: Date | null dateProp().required; // → prop type: Date dateProp().withDefault(() => new Date()); // → prop type: DateAllows any symbol (validated at runtime and compile time).
symbolProp().optional; // → prop type: symbol | undefined symbolProp().nullable; // → prop type: symbol | null symbolProp().required; // → prop type: symbol symbolProp().withDefault(Symbol('foo')); // → prop type: symbolAllows any Vue component instance, name or options object. No built-in runtime validation is performed by default.
vueComponentProp().optional; // → prop type: VueComponent | undefined vueComponentProp().nullable; // → prop type: VueComponent | null vueComponentProp().required; // → prop type: VueComponent vueComponentProp().withDefault('close-icon'); // → prop type: VueComponentℹ️ Note:
The typeVueComponentis defined to beobject | string. It has to be so broad to allow Vue 2 and Vue 3 component options or instances. If you are able to narrow the type without pulling in heavy dependencies, please open an issue or pull request!
Allows any type. No built-in runtime validation is performed by default.
Type parameter T can be used to restrict the type at compile time.
anyProp().optional; // → prop type: any anyProp().nullable; // → prop type: any anyProp().required; // → prop type: any anyProp().withDefault('foo'); // → prop type: any anyProp<string>().optional; // → prop type: string | undefined anyProp<string>().nullable; // → prop type: string | null anyProp<string>().required; // → prop type: string anyProp<string>().withDefault('foo'); // → prop type: stringAllows any array. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type of the array items at compile time.
arrayProp().optional; // → prop type: unknown[] | undefined arrayProp().nullable; // → prop type: unknown[] | null arrayProp().required; // → prop type: unknown[] arrayProp().withDefault(() => []); // → prop type: unknown[] arrayProp<string>().optional; // → prop type: string[] | undefined arrayProp<string>().nullable; // → prop type: string[] | null arrayProp<string>().required; // → prop type: string[] arrayProp<string>().withDefault(() => ['foo', 'bar']); // → prop type: string[]Allows any object. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type at compile time.
objectProp().optional; // → prop type: object | undefined objectProp().nullable; // → prop type: object | null objectProp().required; // → prop type: object objectProp().withDefault(() => ({})); // → prop type: object interface User { name: string; } objectProp<User>().optional; // → prop type: User | undefined objectProp<User>().nullable; // → prop type: User | null objectProp<User>().required; // → prop type: User objectProp<User>().withDefault(() => ({ name: 'John' })); // → prop type: UserAllows any function. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type to a specific function signature at compile time.
ℹ️ Note:
There is no.withDefault()function for this prop type.
functionProp().optional; // → prop type: Function | undefined functionProp().nullable; // → prop type: Function | null functionProp().required; // → prop type: Function type MyFunc = (a: number, b: string) => boolean; functionProp<MyFunc>().optional; // → prop type: MyFunc | undefined functionProp<MyFunc>().nullable; // → prop type: MyFunc | null functionProp<MyFunc>().required; // → prop type: MyFuncAllows any of the specified allowed values (validated at runtime and compile time).
Type parameter T can be used to adjust the inferred type at compile time, this is usually not necessary.
ℹ️ Note:
Proper type checking is only possible if the allowed values are readonly, usually throughas const.
oneOfProp(['foo', 'bar'] as const).optional; // → prop type: 'foo' | 'bar' | undefined oneOfProp(['foo', 'bar'] as const).nullable; // → prop type: 'foo' | 'bar' | null oneOfProp(['foo', 'bar'] as const).required; // → prop type: 'foo' | 'bar' oneOfProp(['foo', 'bar'] as const).withDefault('foo'); // → prop type: 'foo' | 'bar'Allows any of the keys of the specified object (validated at runtime and compile time).
Type parameter T can be used to adjust the inferred type at compile time, this is usually not necessary.
oneOfObjectKeysProp({ foo: 1, bar: 2 }).optional; // → prop type: 'foo' | 'bar' | undefined oneOfObjectKeysProp({ foo: 1, bar: 2 }).nullable; // → prop type: 'foo' | 'bar' | null oneOfObjectKeysProp({ foo: 1, bar: 2 }).required; // → prop type: 'foo' | 'bar' oneOfObjectKeysProp({ foo: 1, bar: 2 }).withDefault('foo'); // → prop type: 'foo' | 'bar'Allows any of the passed constructor types (validated at runtime).
Type parameter T has to be used to adjust the type at compile time.
oneOfTypesProp<number | string>([Number, String]).optional; // → prop type: string | number | undefined oneOfTypesProp<number | string>([Number, String]).nullable; // → prop type: string | number | null oneOfTypesProp<number | string>([Number, String]).required; // → prop type: string | number oneOfTypesProp<number | string>([Number, String]).withDefault(42); // → prop type: string | numberAllows instances of the given constructor (validated at runtime and compile time).
Type parameter T can be used to adjust the inferred type at compile time.
instanceOfProp(Date).optional; // → prop type: Date | undefined instanceOfProp(Date).nullable; // → prop type: Date | null instanceOfProp(Date).required; // → prop type: Date instanceOfProp(Date).withDefault(() => new Date()); // → prop type: DatePlease see CONTRIBUTING.md.
Unless otherwise noted, all source code is licensed under the MIT License.
Copyright (c) 2022 Flo Edelmann