1# Overlays
2 
3**Prerequisite**: All overlays require `<UApp>` wrapper in app root.
4 
5**Important:** v4.4.0 includes security fixes for XSS vulnerabilities in Banner and CommandPalette components. Upgrade recommended.
6 
7## Toast (Notifications)
8 
9### Basic Usage
10 
11```vue
12<script setup>
13const toast = useToast()
14 
15function showToast() {
16  toast.add({
17    title: 'Success!',
18    description: 'Your changes have been saved.',
19    color: 'success',
20    icon: 'i-heroicons-check-circle'
21  })
22}
23</script>
24 
25<template>
26  <UButton @click="showToast">Show Toast</UButton>
27</template>
28```
29 
30### Toast Options
31 
32```ts
33toast.add({
34  id: 'unique-id', // Custom ID (auto-generated if omitted)
35  title: 'Title', // Toast title
36  description: 'Details', // Toast body
37  color: 'success', // primary, success, error, warning, info
38  icon: 'i-heroicons-check', // Left icon
39  avatar: { src: '...' }, // Avatar instead of icon
40  timeout: 5000, // Auto-dismiss (0 = never)
41  actions: [{ // Action buttons
42    label: 'Undo',
43    click: () => {}
44  }],
45  callback: () => {} // Called on dismiss
46})
47```
48 
49### Toast Types
50 
51```ts
52// Success
53toast.add({ title: 'Saved', color: 'success', icon: 'i-heroicons-check-circle' })
54 
55// Error
56toast.add({ title: 'Error', color: 'error', icon: 'i-heroicons-x-circle' })
57 
58// Warning
59toast.add({ title: 'Warning', color: 'warning', icon: 'i-heroicons-exclamation-triangle' })
60 
61// Info
62toast.add({ title: 'Info', color: 'info', icon: 'i-heroicons-information-circle' })
63 
64// Remove toast
65toast.remove('toast-id')
66 
67// Clear all
68toast.clear()
69```
70 
71## Modal
72 
73### Basic Modal
74 
75```vue
76<script setup>
77const isOpen = ref(false)
78</script>
79 
80<template>
81  <UButton @click="isOpen = true">Open Modal</UButton>
82 
83  <UModal v-model:open="isOpen">
84    <template #header>
85      <h3>Modal Title</h3>
86    </template>
87 
88    <p>Modal content goes here...</p>
89 
90    <template #footer>
91      <UButton variant="ghost" @click="isOpen = false">Cancel</UButton>
92      <UButton @click="save">Save</UButton>
93    </template>
94  </UModal>
95</template>
96```
97 
98### Modal Props
99 
100```vue
101<UModal
102  v-model:open="isOpen"
103  title="Modal Title"          <!-- Alternative to #header slot -->
104  description="Subtitle"       <!-- Below title -->
105  :close="true"                <!-- Show close button -->
106  :close-icon="'i-heroicons-x-mark'"
107  :overlay="true"              <!-- Show backdrop -->
108  :transition="true"           <!-- Enable animation -->
109  :prevent-close="false"       <!-- Prevent close on overlay click -->
110  fullscreen                   <!-- Full screen mode -->
111>
112```
113 
114### Programmatic Modal (useOverlay)
115 
116```vue
117<script setup>
118const overlay = useOverlay()
119 
120async function openConfirm() {
121  const modal = overlay.create(ConfirmModal, {
122    props: { title: 'Confirm action?' },
123    events: {
124      confirm: () => modal.close(true),
125      cancel: () => modal.close(false)
126    }
127  })
128 
129  const result = await modal.result
130  if (result) {
131    // User confirmed
132  }
133}
134</script>
135```
136 
137## Slideover
138 
139Side panel overlay (from edge of screen).
140 
141```vue
142<script setup>
143const isOpen = ref(false)
144</script>
145 
146<template>
147  <UButton @click="isOpen = true">Open Slideover</UButton>
148 
149  <USlideover v-model:open="isOpen" title="Settings" side="right">
150    <div class="p-4">
151      Settings content...
152    </div>
153  </USlideover>
154</template>
155```
156 
157### Slideover Props
158 
159```vue
160<USlideover
161  v-model:open="isOpen"
162  title="Title"
163  description="Subtitle"
164  side="right"              <!-- left, right, top, bottom -->
165  :overlay="true"
166  :transition="true"
167  :prevent-close="false"
168>
169```
170 
171## Drawer
172 
173Bottom sheet overlay (vaul-vue).
174 
175```vue
176<script setup>
177const isOpen = ref(false)
178</script>
179 
180<template>
181  <UButton @click="isOpen = true">Open Drawer</UButton>
182 
183  <UDrawer v-model:open="isOpen">
184    <div class="p-4">
185      Drawer content...
186    </div>
187  </UDrawer>
188</template>
189```
190 
191### Drawer Props
192 
193```vue
194<UDrawer
195  v-model:open="isOpen"
196  title="Drawer Title"
197  description="Subtitle"
198  handle                     <!-- Show drag handle -->
199  :should-scale-background="true"
200  :close-threshold="0.25"    <!-- Swipe threshold to close -->
201>
202```
203 
204## Popover
205 
206```vue
207<UPopover>
208  <UButton>Open Popover</UButton>
209 
210  <template #content>
211    <div class="p-4">
212      Popover content
213    </div>
214  </template>
215</UPopover>
216```
217 
218### Popover Props
219 
220```vue
221<UPopover
222  :open="isOpen"
223  side="bottom"              <!-- top, right, bottom, left -->
224  align="center"             <!-- start, center, end -->
225  :arrow="true"
226  :delay="{ open: 0, close: 0 }"
227>
228```
229 
230## Tooltip
231 
232```vue
233<UTooltip text="Helpful tip">
234  <UButton icon="i-heroicons-question-mark-circle" />
235</UTooltip>
236 
237<!-- With slot content -->
238<UTooltip>
239  <UButton>Hover me</UButton>
240  <template #content>
241    <p>Rich tooltip content</p>
242  </template>
243</UTooltip>
244```
245 
246## DropdownMenu
247 
248```vue
249<script setup>
250const items = [
251  { label: 'Edit', icon: 'i-heroicons-pencil', click: () => {} },
252  { label: 'Duplicate', icon: 'i-heroicons-document-duplicate' },
253  { type: 'separator' },
254  { label: 'Delete', icon: 'i-heroicons-trash', color: 'error' }
255]
256</script>
257 
258<template>
259  <UDropdownMenu :items="items">
260    <UButton icon="i-heroicons-ellipsis-vertical" variant="ghost" />
261  </UDropdownMenu>
262</template>
263```
264 
265### Nested Items
266 
267```vue
268<script setup>
269const items = [
270  { label: 'New', children: [
271    { label: 'File', click: () => {} },
272    { label: 'Folder', click: () => {} }
273  ]},
274  { label: 'Delete' }
275]
276</script>
277```
278 
279## ContextMenu
280 
281Right-click menu.
282 
283```vue
284<UContextMenu :items="items">
285  <div class="h-40 border rounded flex items-center justify-center">
286    Right-click here
287  </div>
288</UContextMenu>
289```
290 
291## CommandPalette
292 
293Search-driven command menu (Fuse.js powered).
294 
295```vue
296<script setup>
297const isOpen = ref(false)
298 
299const groups = [{
300  key: 'actions',
301  label: 'Actions',
302  items: [
303    { label: 'New file', icon: 'i-heroicons-document-plus', click: () => {} },
304    { label: 'New folder', icon: 'i-heroicons-folder-plus', click: () => {} }
305  ]
306}, {
307  key: 'navigation',
308  label: 'Navigation',
309  items: [
310    { label: 'Home', to: '/' },
311    { label: 'Settings', to: '/settings' }
312  ]
313}]
314</script>
315 
316<template>
317  <UCommandPalette
318    v-model:open="isOpen"
319    :groups="groups"
320    placeholder="Search..."
321    size="md"
322  />
323</template>
324```
325 
326### CommandPalette Props (v4.4+)
327 
328```vue
329<UCommandPalette
330  v-model:open="isOpen"
331  :groups="groups"
332  placeholder="Search..."
333  size="md"              <!-- Size: sm, md, lg (v4.4+) -->
334  :input="{ /* props */ }"  <!-- Custom input props (v4.4+) -->
335/>
336```
337 
338### Keyboard Shortcut
339 
340```vue
341<script setup>
342defineShortcuts({
343  meta_k: () => { isOpen.value = true }
344})
345</script>
346```
347 
348## Best Practices
349 
350| Do                                     | Don't                       |
351| -------------------------------------- | --------------------------- |
352| Use useToast for notifications         | Build custom toast systems  |
353| Use UModal for dialogs                 | Use alerts for complex UI   |
354| Use Slideover for panels               | Use modals for side content |
355| Use Drawer for mobile sheets           | Use slideover on mobile     |
356| Use CommandPalette for search          | Build custom search UI      |
357| Use programmatic overlays for confirms | Create confirm components   |
358