data option signature and behavior
The data option is a function that returns the initial reactive state for the component instance. The function signature is: data?(this: ComponentPublicInstance, vm: ComponentPublicInstance): object. The function must return a plain JavaScript object, which Vue will make reactive. After the instance is created, the reactive data object can be accessed as this.$data. The component instance proxies all properties found on the data object, so this.a is equivalent to this.$data.a.
data option property requirements
All top-level data properties must be included in the returned data object. Properties that start with _ or $ will not be proxied on the component instance because they may conflict with Vue's internal properties and API methods; they must be accessed as this.$data._property. If a property value is not yet available, an empty value such as undefined or null should be included as a placeholder to ensure Vue knows the property exists.
data option return value recommendations
It is not recommended to return objects with their own stateful behavior like browser API objects and prototype properties. The returned object should ideally be a plain object that only represents the state of the component. Adding new properties to this.$data after the instance is created is possible but not recommended.
data option with arrow function
If you use an arrow function with the data property, this won't be the component's instance, but you can still access the instance as the function's first argument: data: (vm) => ({ a: vm.myProp })
props option syntax and types
The props option can be declared in two forms: simple form using an array of strings (type ArrayPropsOptions = string[]), or full form using an object where each property key is the prop name and the value is the prop's type or advanced options (type ObjectPropsOptions = { [key: string]: Prop }). The Prop type is: Prop<T = any> = PropOptions<T> | PropType<T> | null.
PropOptions interface
PropOptions<T> has the following properties: type?: PropType<T> (the constructor function or array of constructors); required?: boolean (defines if the prop is required, defaults to false); default?: T | ((rawProps: object) => T) (specifies a default value when not passed or undefined, with object/array defaults requiring a factory function); validator?: (value: unknown, rawProps: object) => boolean (custom validator function).
PropType definition
PropType<T> = { new (): T } | { new (): T }[] - a constructor function or an array of constructor functions.
prop type validation and boolean casting
The type option can be one of the following native constructors: String, Number, Boolean, Array, Object, Date, Function, Symbol, any custom constructor function, or an array of those. In development mode, Vue will check if a prop's value matches the declared type and throw a warning if it doesn't. A prop with Boolean type affects its value casting behavior in both development and production.
prop default value behavior
The default option specifies a default value for the prop when it is not passed by the parent or has undefined value. Object or array defaults must be returned using a factory function. The factory function receives the raw props object as the argument.
prop required option
The required option defines if the prop is required. In a non-production environment, a console warning will be thrown if this value is truthy and the prop is not passed.
prop validator function
The validator option is a custom validator function that takes the prop value and props object as arguments: (value: unknown, rawProps: object) => boolean. In development mode, a console warning will be thrown if this function returns a falsy value (i.e. the validation fails).
computed option signature
The computed option accepts an object where the key is the name of the computed property, and the value is either a computed getter (type ComputedGetter<T> = (this: ComponentPublicInstance, vm: ComponentPublicInstance, previous?: T) => T) or an object with get and set methods (type WritableComputedOptions<T> = { get: ComputedGetter<T>, set: ComputedSetter<T> }).
ComputedSetter signature
ComputedSetter<T> = (this: ComponentPublicInstance, value: T) => void
computed property this binding
All getters and setters in computed properties have their this context automatically bound to the component instance. If you use an arrow function with a computed property, this won't point to the component's instance, but you can still access the instance as the function's first argument: computed: { aDouble: (vm) => vm.a * 2 }
methods option signature
The methods option has type: methods?: { [key: string]: (this: ComponentPublicInstance, ...args: any[]) => any }. Declared methods can be directly accessed on the component instance or used in template expressions.
methods option this binding and arrow functions
All methods have their this context automatically bound to the component instance, even when passed around. Avoid using arrow functions when declaring methods, as they will not have access to the component instance via this.
watch option syntax and types
The watch option expects an object where keys are the reactive component instance properties to watch (e.g. properties declared via data or computed), and values are the corresponding callbacks. Type: watch?: { [key: string]: WatchOptionItem | WatchOptionItem[] }. WatchOptionItem = string | WatchCallback | ObjectWatchOptionItem.
WatchCallback signature
WatchCallback<T> = (value: T, oldValue: T, onCleanup: (cleanupFn: () => void) => void) => void. The callback receives the new value, old value, and a function to register cleanup functions.
ObjectWatchOptionItem properties
ObjectWatchOptionItem has the following properties: handler: WatchCallback | string (the callback or method name); immediate?: boolean (trigger immediately on watcher creation, default false); deep?: boolean (force deep traversal for object/array, default false); flush?: 'pre' | 'post' | 'sync' (adjust callback flush timing, default 'pre'); onTrack?: (event: DebuggerEvent) => void (debug the watcher's dependencies); onTrigger?: (event: DebuggerEvent) => void (debug when watcher triggers).
watch key paths and complex expressions
In addition to a root-level property, the watch key can also be a simple dot-delimited path, e.g. 'a.b.c'. Note that this usage does not support complex expressions - only dot-delimited paths are supported. If you need to watch complex data sources, use the imperative $watch() API instead.
watch option string method syntax
The watch value can be a string of a method name (declared via methods), which allows using method names as watch callbacks.
watch option immediate mode
When immediate is true, the callback is triggered immediately on watcher creation. The old value will be undefined on the first call.
watch option deep mode
When deep is true, the source (if it is an object or array) will be deeply traversed, so that the callback fires on deep mutations.
watch option flush modes
The flush option adjusts the callback's flush timing with three possible values: 'pre' (callback is called before component updates, default), 'post' (callback is called after component updates), 'sync' (callback is called synchronously).
watch option arrow function warning
Avoid using arrow functions when declaring watch callbacks as they will not have access to the component instance via this.
watch option array syntax
The watch value can be an array of callbacks (WatchOptionItem[]), and they will be called one-by-one.
emits option syntax and types
The emits option can be declared in two forms: simple form using an array of strings (type ArrayEmitsOptions = string[]), or full form using an object where each property key is the event name and the value is either null or a validator function (type ObjectEmitsOptions = { [key: string]: EmitValidator | null }).
EmitValidator signature
EmitValidator = (...args: unknown[]) => boolean. The validation function receives the additional arguments passed to the component's $emit call. The validator function should return a boolean to indicate whether the event arguments are valid.
emits option effect on event listeners
The emits option affects which event listeners are considered component event listeners rather than native DOM event listeners. The listeners for declared events will be removed from the component's $attrs object, so they will not be passed through to the component's root element.
expose option signature
The expose option has type: expose?: string[]. It declares exposed public properties when the component instance is accessed by a parent via template refs.
expose option behavior
By default, a component instance exposes all instance properties to the parent when accessed via $parent, $root, or template refs. When expose is used, only the properties explicitly listed in the array will be exposed on the component's public instance. expose only affects user-defined properties - it does not filter out built-in component instance properties.
What is a prop in Vue
A prop in Vue is a way for a component to accept data from its parent component. Props must be explicitly declared using the props option. They can be declared in two forms: simple form using an array of strings listing prop names, or full form using an object where each property key is the prop name and the value specifies the prop's type and optional validation rules (required, default, validator). Props are passed from parent to child components and should be treated as read-only within the child component.
data() option returns object for reactive state
With the Options API, the data option must be a function that returns an object. Vue calls this function when creating a new component instance and wraps the returned object in its reactivity system. Top-level properties of this object are proxied on the component instance (this in methods and lifecycle hooks).
methods option contains component methods
With the Options API, the methods option is an object containing desired methods. These can be called in lifecycle hooks, other methods, or from templates. Methods are most commonly used as event listeners in templates.
Vue automatically binds this for methods
Vue automatically binds the this value for methods so that it always refers to the component instance. This ensures a method retains the correct this value if used as an event listener or callback. Avoid using arrow functions when defining methods, as that prevents Vue from binding the appropriate this value.
Data properties must exist in data() return object
With the Options API, you need to ensure all desired properties are present in the object returned by the data function when the instance is first created. Where necessary, use null, undefined or other placeholder values for properties where the desired value isn't yet available. Properties added directly to this without including in data will not be able to trigger reactive updates.
Stateful methods need independent copies per instance
When dynamically creating a method function like a debounced event handler, if multiple component instances share the same debounced function they will interfere with one another because the debounced function is stateful. To keep each component instance's debounced function independent, create the debounced version in the created lifecycle hook: this.debouncedClick = debounce(this.click, 500). Also cancel the timer when the component is removed in the unmounted hook: this.debouncedClick.cancel().