1---
2name: script-setup-macros
3description: Vue 3 script setup syntax and compiler macros for defining props, emits, models, and more
4---
5 
6# Script Setup & Macros
7 
8`<script setup>` is the recommended syntax for Vue SFCs with Composition API. It provides better runtime performance and IDE type inference.
9 
10## Basic Syntax
11 
12```vue
13<script setup lang="ts">
14// Top-level bindings are exposed to template
15import { ref } from 'vue'
16import MyComponent from './MyComponent.vue'
17 
18const count = ref(0)
19const increment = () => count.value++
20</script>
21 
22<template>
23  <button @click="increment">{{ count }}</button>
24  <MyComponent />
25</template>
26```
27 
28## defineProps
29 
30Declare component props with full TypeScript support.
31 
32```ts
33// Type-based declaration (recommended)
34const props = defineProps<{
35  title: string
36  count?: number
37  items: string[]
38}>()
39 
40// With defaults (Vue 3.5+)
41const { title, count = 0 } = defineProps<{
42  title: string
43  count?: number
44}>()
45 
46// With defaults (Vue 3.4 and below)
47const props = withDefaults(defineProps<{
48  title: string
49  items?: string[]
50}>(), {
51  items: () => []  // Use factory for arrays/objects
52})
53```
54 
55## defineEmits
56 
57Declare emitted events with typed payloads.
58 
59```ts
60// Named tuple syntax (recommended)
61const emit = defineEmits<{
62  update: [value: string]
63  change: [id: number, name: string]
64  close: []
65}>()
66 
67emit('update', 'new value')
68emit('change', 1, 'name')
69emit('close')
70```
71 
72## defineModel
73 
74Two-way binding prop consumed via `v-model`. Available in Vue 3.4+.
75 
76```ts
77// Basic usage - creates "modelValue" prop
78const model = defineModel<string>()
79model.value = 'hello'  // Emits "update:modelValue"
80 
81// Named model - consumed via v-model:name
82const count = defineModel<number>('count', { default: 0 })
83 
84// With modifiers
85const [value, modifiers] = defineModel<string>()
86if (modifiers.trim) {
87  // Handle trim modifier
88}
89 
90// With transformers
91const [value, modifiers] = defineModel({
92  get(val) { return val?.toLowerCase() },
93  set(val) { return modifiers.trim ? val?.trim() : val }
94})
95```
96 
97Parent usage:
98```vue
99<Child v-model="name" />
100<Child v-model:count="total" />
101<Child v-model.trim="text" />
102```
103 
104## defineExpose
105 
106Explicitly expose properties to parent via template refs. Components are closed by default.
107 
108```ts
109import { ref } from 'vue'
110 
111const count = ref(0)
112const reset = () => { count.value = 0 }
113 
114defineExpose({
115  count,
116  reset
117})
118```
119 
120Parent access:
121```ts
122const childRef = ref<{ count: number; reset: () => void }>()
123childRef.value?.reset()
124```
125 
126## defineOptions
127 
128Declare component options without a separate `<script>` block. Available in Vue 3.3+.
129 
130```ts
131defineOptions({
132  inheritAttrs: false,
133  name: 'CustomName'
134})
135```
136 
137## defineSlots
138 
139Provide type hints for slot props. Available in Vue 3.3+.
140 
141```ts
142const slots = defineSlots<{
143  default(props: { item: string; index: number }): any
144  header(props: { title: string }): any
145}>()
146```
147 
148## Generic Components
149 
150Declare generic type parameters using the `generic` attribute.
151 
152```vue
153<script setup lang="ts" generic="T extends string | number">
154defineProps<{
155  items: T[]
156  selected: T
157}>()
158</script>
159```
160 
161Multiple generics with constraints:
162```vue
163<script setup lang="ts" generic="T, U extends Record<string, T>">
164import type { Item } from './types'
165defineProps<{
166  data: U
167  key: keyof U
168}>()
169</script>
170```
171 
172## Local Custom Directives
173 
174Use `vNameOfDirective` naming convention.
175 
176```ts
177const vFocus = {
178  mounted: (el: HTMLElement) => el.focus()
179}
180 
181// Or import and rename
182import { myDirective as vMyDirective } from './directives'
183```
184 
185```vue
186<template>
187  <input v-focus />
188</template>
189```
190 
191## Top-level await
192 
193Use `await` directly in `<script setup>`. The component becomes async and must be used with `<Suspense>`.
194 
195```vue
196<script setup lang="ts">
197const data = await fetch('/api/data').then(r => r.json())
198</script>
199```
200 
201<!--
202Source references:
203- https://vuejs.org/api/sfc-script-setup.html
204-->
205