1# Composables
2 
3## useToast
4 
5Show notifications. Requires `<UApp>` wrapper.
6 
7```ts
8const toast = useToast()
9 
10// Add toast
11toast.add({
12  title: 'Success',
13  description: 'Item saved',
14  color: 'success',
15  icon: 'i-heroicons-check-circle',
16  timeout: 5000
17})
18 
19// Remove specific toast
20toast.remove('toast-id')
21 
22// Clear all toasts
23toast.clear()
24```
25 
26See overlays.md for full toast options.
27 
28## useOverlay
29 
30Programmatically create modals, slidelovers, drawers.
31 
32```ts
33const overlay = useOverlay()
34 
35// Create modal
36const modal = overlay.create(MyModalComponent, {
37  props: { title: 'Confirm' },
38  modal: true // Default: true
39})
40 
41// Wait for result
42const result = await modal.result
43 
44// Close programmatically
45modal.close(returnValue)
46```
47 
48### Confirm Dialog Pattern
49 
50```vue
51<!-- ConfirmDialog.vue -->
52<script setup>
53const props = defineProps<{ title: string; message: string }>()
54const emit = defineEmits(['confirm', 'cancel'])
55</script>
56 
57<template>
58  <UModal :open="true">
59    <template #header>{{ title }}</template>
60    <p>{{ message }}</p>
61    <template #footer>
62      <UButton variant="ghost" @click="emit('cancel')">Cancel</UButton>
63      <UButton color="error" @click="emit('confirm')">Confirm</UButton>
64    </template>
65  </UModal>
66</template>
67```
68 
69```ts
70// Usage
71const overlay = useOverlay()
72 
73async function confirmDelete() {
74  const modal = overlay.create(ConfirmDialog, {
75    props: { title: 'Delete?', message: 'This cannot be undone.' },
76    events: {
77      confirm: () => modal.close(true),
78      cancel: () => modal.close(false)
79    }
80  })
81 
82  if (await modal.result) {
83    // Delete item
84  }
85}
86```
87 
88## defineShortcuts
89 
90Define keyboard shortcuts.
91 
92```ts
93defineShortcuts({
94  // Single key
95  escape: () => closeModal(),
96 
97  // Modifier + key (meta = Cmd on Mac, Ctrl on Windows)
98  meta_k: () => openSearch(),
99  meta_shift_p: () => openCommandPalette(),
100 
101  // Ctrl specific
102  ctrl_s: () => save(),
103 
104  // Alt/Option
105  alt_n: () => newItem(),
106 
107  // Arrow keys
108  arrowup: () => navigateUp(),
109  arrowdown: () => navigateDown(),
110 
111  // With condition
112  meta_enter: {
113    handler: () => submit(),
114    whenever: [isFormValid]
115  }
116}, {
117  layoutIndependent: true // Ignore keyboard layout (v4.3+)
118})
119```
120 
121### Shortcut Syntax
122 
123| Key     | Meaning                    |
124| ------- | -------------------------- |
125| `meta`  | Cmd (Mac) / Ctrl (Windows) |
126| `ctrl`  | Ctrl key                   |
127| `alt`   | Alt / Option key           |
128| `shift` | Shift key                  |
129| `_`     | Key separator              |
130 
131### Extract Shortcuts (for display)
132 
133```ts
134const shortcuts = extractShortcuts({
135  meta_k: () => {},
136  escape: () => {}
137})
138// Returns: { meta_k: { key: 'K', metaKey: true }, ... }
139```
140 
141## useKbd
142 
143Detect current keyboard state.
144 
145```ts
146const kbd = useKbd()
147 
148// Reactive state
149kbd.meta // true if Cmd/Ctrl pressed
150kbd.ctrl // true if Ctrl pressed
151kbd.shift // true if Shift pressed
152kbd.alt // true if Alt/Option pressed
153```
154 
155## useScrollspy
156 
157Track scroll position for anchor navigation.
158 
159```ts
160const { activeId } = useScrollspy({
161  ids: ['section-1', 'section-2', 'section-3'],
162  offset: 100 // Pixels from top
163})
164 
165// activeId.value = 'section-2' (currently visible)
166```
167 
168### With Table of Contents
169 
170```vue
171<script setup>
172const sections = ['intro', 'features', 'pricing']
173const { activeId } = useScrollspy({ ids: sections })
174</script>
175 
176<template>
177  <nav>
178    <a
179      v-for="id in sections"
180      :href="`#${id}`"
181      :class="{ 'font-bold': activeId === id }"
182    >
183      {{ id }}
184    </a>
185  </nav>
186</template>
187```
188 
189## useFileUpload
190 
191Handle file uploads.
192 
193```ts
194const { files, open, reset, remove } = useFileUpload({
195  accept: 'image/*',
196  multiple: true,
197  maxFiles: 5,
198  maxSize: 5 * 1024 * 1024 // 5MB
199})
200 
201// Open file picker
202open()
203 
204// Files selected
205files.value // FileList
206 
207// Reset selection
208reset()
209 
210// Remove specific file
211remove(index)
212```
213 
214### With UFileUpload
215 
216```vue
217<script setup>
218const { files, open, reset } = useFileUpload()
219</script>
220 
221<template>
222  <UFileUpload v-model="files" accept="image/*" @change="handleFiles">
223    <template #default="{ dragover }">
224      <div :class="{ 'border-primary': dragover }">
225        Drop files here or <UButton @click="open">Browse</UButton>
226      </div>
227    </template>
228  </UFileUpload>
229</template>
230```
231 
232## defineLocale
233 
234Define/extend locale for i18n.
235 
236```ts
237// locales/es.ts
238export default defineLocale({
239  name: 'Español',
240  code: 'es',
241  messages: {
242    select: {
243      placeholder: 'Seleccionar...',
244      noResults: 'Sin resultados'
245    },
246    pagination: {
247      previous: 'Anterior',
248      next: 'Siguiente'
249    }
250  }
251})
252```
253 
254### Extend Existing Locale
255 
256```ts
257import en from '@nuxt/ui/locale/en'
258 
259export default extendLocale(en, {
260  messages: {
261    select: {
262      placeholder: 'Choose an option...'
263    }
264  }
265})
266```
267 
268### Use in App
269 
270```vue
271<script setup>
272import es from '~/locales/es'
273</script>
274 
275<template>
276  <UApp :locale="es">
277    <NuxtPage />
278  </UApp>
279</template>
280```
281 
282## useFormField
283 
284Access form field context in custom components.
285 
286```ts
287// Inside custom form component
288const { name, error, disabled } = useFormField()
289 
290// name: field name from UFormField
291// error: validation error message
292// disabled: if field is disabled
293```
294 
295### Custom Input Component
296 
297```vue
298<script setup>
299const props = defineProps<{ modelValue: string }>()
300const emit = defineEmits(['update:modelValue'])
301 
302const { error } = useFormField()
303</script>
304 
305<template>
306  <input
307    :value="modelValue"
308    :class="{ 'border-error': error }"
309    @input="emit('update:modelValue', $event.target.value)"
310  />
311  <span v-if="error" class="text-error">{{ error }}</span>
312</template>
313```
314 
315## Quick Reference
316 
317| Composable         | Purpose                         |
318| ------------------ | ------------------------------- |
319| `useToast`         | Show notifications              |
320| `useOverlay`       | Programmatic modals/slidelovers |
321| `defineShortcuts`  | Keyboard shortcuts              |
322| `useKbd`           | Keyboard state detection        |
323| `useScrollspy`     | Track scroll for TOC            |
324| `useFileUpload`    | File upload handling            |
325| `defineLocale`     | i18n locale definition          |
326| `extendLocale`     | Extend existing locale          |
327| `useFormField`     | Form field context              |
328| `extractShortcuts` | Parse shortcut definitions      |
329