0
# Component Properties
1

2
Property-related decorators for component props, model binding, and template references. These decorators handle the binding between component data and external properties, enabling reactive data flow and template reference access.
3

4
## Capabilities
5

6
### Prop Decorator
7

8
Declares component properties with optional type validation, default values, and required constraints.
9

10
```typescript { .api }
11
/**
12
 * Declares component properties with optional type validation and defaults
13
 * @param options - PropOptions object, Constructor array, or single Constructor (optional, defaults to {})
14
 * @returns Property decorator function
15
 */
16
function Prop(options: PropOptions | Constructor[] | Constructor = {}): PropertyDecorator;
17

18
interface PropOptions {
19
  type?: PropType<any> | true;
20
  required?: boolean;
21
  default?: any;
22
  validator?(value: any): boolean;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { Vue, Component, Prop } from "vue-property-decorator";
30

31
@Component
32
export default class MyComponent extends Vue {
33
  // Basic prop with automatic type inference
34
  @Prop()
35
  message!: string;
36

37
  // Required prop with explicit type
38
  @Prop({ type: String, required: true })
39
  title!: string;
40

41
  // Prop with default value
42
  @Prop({ default: 42 })
43
  count!: number;
44

45
  // Prop with multiple types
46
  @Prop([String, Number])
47
  value!: string | number;
48

49
  // Prop with validator
50
  @Prop({
51
    type: String,
52
    validator: (value) => ["small", "medium", "large"].includes(value)
53
  })
54
  size!: string;
55
}
56
```
57

58
### PropSync Decorator
59

60
Creates two-way binding for properties with automatic update event emission, combining prop reception with sync modifier support.
61

62
```typescript { .api }
63
/**
64
 * Creates two-way binding for properties with automatic update event emission
65
 * @param propName - External property name (required)
66
 * @param options - PropOptions object, Constructor array, or single Constructor (optional, defaults to {})
67
 * @returns Property decorator function
68
 */
69
function PropSync(propName: string, options: PropOptions | Constructor[] | Constructor = {}): PropertyDecorator;
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { Vue, Component, PropSync } from "vue-property-decorator";
76

77
@Component
78
export default class MyComponent extends Vue {
79
  // Creates syncedValue prop with update:syncedValue event
80
  @PropSync("value", { type: String })
81
  syncedValue!: string;
82

83
  // Usage in template will automatically emit update events
84
  updateValue() {
85
    this.syncedValue = "new value"; // Emits update:value
86
  }
87
}
88
```
89

90
### Model Decorator
91

92
Defines the model property and event for custom v-model implementation, allowing components to work seamlessly with v-model directive.
93

94
```typescript { .api }
95
/**
96
 * Defines the model property and event for custom v-model implementation
97
 * @param event - Event name (optional, defaults to property key)
98
 * @param options - PropOptions object, Constructor array, or single Constructor (optional, defaults to {})
99
 * @returns Property decorator function
100
 */
101
function Model(event?: string, options: PropOptions | Constructor[] | Constructor = {}): PropertyDecorator;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { Vue, Component, Model } from "vue-property-decorator";
108

109
@Component
110
export default class CustomInput extends Vue {
111
  // Default v-model implementation (value prop, input event)
112
  @Model("input", { type: String })
113
  value!: string;
114

115
  // Custom model with different event
116
  @Model("change", { type: Boolean })
117
  checked!: boolean;
118

119
  handleInput(event: Event) {
120
    const target = event.target as HTMLInputElement;
121
    this.$emit("input", target.value);
122
  }
123
}
124
```
125

126
### ModelSync Decorator
127

128
Combines Model and PropSync functionality for complete v-model with sync behavior, providing both model definition and automatic update handling.
129

130
```typescript { .api }
131
/**
132
 * Combines Model and PropSync functionality for complete v-model with sync behavior
133
 * @param propName - External property name (required)
134
 * @param event - Event name (optional, defaults to property key)
135
 * @param options - PropOptions object, Constructor array, or single Constructor (optional, defaults to {})
136
 * @returns Property decorator function
137
 */
138
function ModelSync(propName: string, event?: string, options: PropOptions | Constructor[] | Constructor = {}): PropertyDecorator;
139
```
140

141
**Usage Examples:**
142

143
```typescript
144
import { Vue, Component, ModelSync } from "vue-property-decorator";
145

146
@Component
147
export default class AdvancedInput extends Vue {
148
  // Creates a model with automatic sync behavior
149
  @ModelSync("value", "input", { type: String })
150
  internalValue!: string;
151

152
  // Changes to internalValue automatically emit the specified event
153
  updateValue(newValue: string) {
154
    this.internalValue = newValue; // Automatically emits 'input' event
155
  }
156
}
157
```
158

159
### VModel Decorator
160

161
Creates standard v-model implementation using 'value' prop and 'input' event, providing a simplified approach for standard form controls.
162

163
```typescript { .api }
164
/**
165
 * Creates standard v-model implementation using 'value' prop and 'input' event
166
 * @param options - PropOptions object (optional, defaults to {})
167
 * @returns Property decorator function
168
 */
169
function VModel(options: PropOptions = {}): PropertyDecorator;
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
import { Vue, Component, VModel } from "vue-property-decorator";
176

177
@Component
178
export default class StandardInput extends Vue {
179
  // Standard v-model implementation
180
  @VModel({ type: String })
181
  value!: string;
182

183
  handleChange(event: Event) {
184
    const target = event.target as HTMLInputElement;
185
    this.value = target.value; // Automatically emits 'input' event
186
  }
187
}
188
```
189

190
### Ref Decorator
191

192
Creates computed property for accessing template references, providing type-safe access to DOM elements and child components.
193

194
```typescript { .api }
195
/**
196
 * Creates computed property for accessing template references
197
 * @param refKey - Template ref name (optional, defaults to property name)
198
 * @returns Property decorator function
199
 */
200
function Ref(refKey?: string): PropertyDecorator;
201
```
202

203
**Usage Examples:**
204

205
```typescript
206
import { Vue, Component, Ref } from "vue-property-decorator";
207

208
@Component
209
export default class MyComponent extends Vue {
210
  // Access element with ref="myInput"
211
  @Ref("myInput")
212
  readonly myInput!: HTMLInputElement;
213

214
  // Access element with ref="myButton" (inferred from property name)
215
  @Ref()
216
  readonly myButton!: HTMLButtonElement;
217

218
  // Access child component
219
  @Ref("childComponent")
220
  readonly childComponent!: Vue;
221

222
  focusInput() {
223
    this.myInput.focus();
224
  }
225

226
  getChildData() {
227
    return (this.childComponent as any).someMethod();
228
  }
229
}
230
```
231

232
## Types
233

234
```typescript { .api }
235
interface PropOptions {
236
  type?: PropType<any> | true;
237
  required?: boolean;
238
  default?: any;
239
  validator?(value: any): boolean;
240
}
241

242
type Constructor = new (...args: any[]) => any;
243
type PropertyDecorator = (target: any, propertyKey: string | symbol) => void;
244
type PropType<T> = Constructor | Constructor[] | PropTypeDefinition<T>;
245

246
interface PropTypeDefinition<T> {
247
  type: Constructor | Constructor[];
248
  default?: T | (() => T);
249
  required?: boolean;
250
  validator?(value: T): boolean;
251
}
252
```