1---
2title: Component Slots Best Practices
3impact: MEDIUM
4impactDescription: Poor slot API design causes empty DOM wrappers, weak TypeScript safety, brittle defaults, and unnecessary component overhead
5type: best-practice
6tags: [vue3, slots, components, typescript, composables]
7---
8 
9# Component Slots Best Practices
10 
11**Impact: MEDIUM** - Slots are a core component API surface in Vue. Structure them intentionally so templates stay predictable, typed, and performant.
12 
13## Task List
14 
15- Use shorthand syntax for named slots (`#` instead of `v-slot:`)
16- Render optional slot wrapper elements only when slot content exists (`$slots` checks)
17- Type scoped slot contracts with `defineSlots` in TypeScript components
18- Provide fallback content for optional slots
19- Prefer composables over renderless components for pure logic reuse
20 
21## Shorthand syntax for named slots
22 
23**BAD:**
24```vue
25<MyComponent>
26  <template v-slot:header> ... </template>
27</MyComponent>
28```
29 
30**GOOD:**
31```vue
32<MyComponent>
33  <template #header> ... </template>
34</MyComponent>
35```
36 
37## Conditionally Render Optional Slot Wrappers
38 
39Use `$slots` checks when wrapper elements add spacing, borders, or layout constraints.
40 
41**BAD:**
42```vue
43<!-- Card.vue -->
44<template>
45  <article class="card">
46    <header class="card-header">
47      <slot name="header" />
48    </header>
49 
50    <section class="card-body">
51      <slot />
52    </section>
53 
54    <footer class="card-footer">
55      <slot name="footer" />
56    </footer>
57  </article>
58</template>
59```
60 
61**GOOD:**
62```vue
63<!-- Card.vue -->
64<template>
65  <article class="card">
66    <header v-if="$slots.header" class="card-header">
67      <slot name="header" />
68    </header>
69 
70    <section v-if="$slots.default" class="card-body">
71      <slot />
72    </section>
73 
74    <footer v-if="$slots.footer" class="card-footer">
75      <slot name="footer" />
76    </footer>
77  </article>
78</template>
79```
80 
81## Type Scoped Slot Props with defineSlots
82 
83In `<script setup lang="ts">`, use `defineSlots` so slot consumers get autocomplete and static checks.
84 
85**BAD:**
86```vue
87<!-- ProductList.vue -->
88<script setup lang="ts">
89interface Product {
90  id: number
91  name: string
92}
93 
94defineProps<{ products: Product[] }>()
95</script>
96 
97<template>
98  <ul>
99    <li v-for="(product, index) in products" :key="product.id">
100      <slot :product="product" :index="index" />
101    </li>
102  </ul>
103</template>
104```
105 
106**GOOD:**
107```vue
108<!-- ProductList.vue -->
109<script setup lang="ts">
110interface Product {
111  id: number
112  name: string
113}
114 
115defineProps<{ products: Product[] }>()
116 
117defineSlots<{
118  default(props: { product: Product; index: number }): any
119  empty(): any
120}>()
121</script>
122 
123<template>
124  <ul v-if="products.length">
125    <li v-for="(product, index) in products" :key="product.id">
126      <slot :product="product" :index="index" />
127    </li>
128  </ul>
129  <slot v-else name="empty" />
130</template>
131```
132 
133## Provide Slot Fallback Content
134 
135Fallback content makes components resilient when parents omit optional slots.
136 
137**BAD:**
138```vue
139<!-- SubmitButton.vue -->
140<template>
141  <button type="submit" class="btn-primary">
142    <slot />
143  </button>
144</template>
145```
146 
147**GOOD:**
148```vue
149<!-- SubmitButton.vue -->
150<template>
151  <button type="submit" class="btn-primary">
152    <slot>Submit</slot>
153  </button>
154</template>
155```
156 
157## Prefer Composables for Pure Logic Reuse
158 
159Renderless components are still useful for slot-driven composition, but composables are usually cleaner for logic-only reuse.
160 
161**BAD:**
162```vue
163<!-- MouseTracker.vue -->
164<script setup lang="ts">
165import { ref, onMounted, onUnmounted } from 'vue'
166 
167const x = ref(0)
168const y = ref(0)
169 
170function onMove(event: MouseEvent) {
171  x.value = event.pageX
172  y.value = event.pageY
173}
174 
175onMounted(() => window.addEventListener('mousemove', onMove))
176onUnmounted(() => window.removeEventListener('mousemove', onMove))
177</script>
178 
179<template>
180  <slot :x="x" :y="y" />
181</template>
182```
183 
184**GOOD:**
185```ts
186// composables/useMouse.ts
187import { ref, onMounted, onUnmounted } from 'vue'
188 
189export function useMouse() {
190  const x = ref(0)
191  const y = ref(0)
192 
193  function onMove(event: MouseEvent) {
194    x.value = event.pageX
195    y.value = event.pageY
196  }
197 
198  onMounted(() => window.addEventListener('mousemove', onMove))
199  onUnmounted(() => window.removeEventListener('mousemove', onMove))
200 
201  return { x, y }
202}
203```
204 
205```vue
206<!-- MousePosition.vue -->
207<script setup lang="ts">
208import { useMouse } from '@/composables/useMouse'
209 
210const { x, y } = useMouse()
211</script>
212 
213<template>
214  <p>{{ x }}, {{ y }}</p>
215</template>
216```
217