Composables

useToast

Show notifications. Requires <UApp> wrapper.

const toast = useToast()

// Add toast
toast.add({
  title: 'Success',
  description: 'Item saved',
  color: 'success',
  icon: 'i-heroicons-check-circle',
  timeout: 5000
})

// Remove specific toast
toast.remove('toast-id')

// Clear all toasts
toast.clear()

See overlays.md for full toast options.

useOverlay

Programmatically create modals, slidelovers, drawers.

const overlay = useOverlay()

// Create modal
const modal = overlay.create(MyModalComponent, {
  props: { title: 'Confirm' },
  modal: true // Default: true
})

// Wait for result
const result = await modal.result

// Close programmatically
modal.close(returnValue)

Confirm Dialog Pattern

<!-- ConfirmDialog.vue -->
<script setup>
const props = defineProps<{ title: string; message: string }>()
const emit = defineEmits(['confirm', 'cancel'])
</script>

<template>
  <UModal :open="true">
    <template #header>{{ title }}</template>
    <p>{{ message }}</p>
    <template #footer>
      <UButton variant="ghost" @click="emit('cancel')">Cancel</UButton>
      <UButton color="error" @click="emit('confirm')">Confirm</UButton>
    </template>
  </UModal>
</template>

// Usage
const overlay = useOverlay()

async function confirmDelete() {
  const modal = overlay.create(ConfirmDialog, {
    props: { title: 'Delete?', message: 'This cannot be undone.' },
    events: {
      confirm: () => modal.close(true),
      cancel: () => modal.close(false)
    }
  })

  if (await modal.result) {
    // Delete item
  }
}

defineShortcuts

Define keyboard shortcuts.

defineShortcuts({
  // Single key
  escape: () => closeModal(),

  // Modifier + key (meta = Cmd on Mac, Ctrl on Windows)
  meta_k: () => openSearch(),
  meta_shift_p: () => openCommandPalette(),

  // Ctrl specific
  ctrl_s: () => save(),

  // Alt/Option
  alt_n: () => newItem(),

  // Arrow keys
  arrowup: () => navigateUp(),
  arrowdown: () => navigateDown(),

  // With condition
  meta_enter: {
    handler: () => submit(),
    whenever: [isFormValid]
  }
}, {
  layoutIndependent: true // Ignore keyboard layout (v4.3+)
})

Shortcut Syntax

Extract Shortcuts (for display)

const shortcuts = extractShortcuts({
  meta_k: () => {},
  escape: () => {}
})
// Returns: { meta_k: { key: 'K', metaKey: true }, ... }

useKbd

Detect current keyboard state.

const kbd = useKbd()

// Reactive state
kbd.meta // true if Cmd/Ctrl pressed
kbd.ctrl // true if Ctrl pressed
kbd.shift // true if Shift pressed
kbd.alt // true if Alt/Option pressed

useScrollspy

Track scroll position for anchor navigation.

const { activeId } = useScrollspy({
  ids: ['section-1', 'section-2', 'section-3'],
  offset: 100 // Pixels from top
})

// activeId.value = 'section-2' (currently visible)

With Table of Contents

<script setup>
const sections = ['intro', 'features', 'pricing']
const { activeId } = useScrollspy({ ids: sections })
</script>

<template>
  <nav>
    <a
      v-for="id in sections"
      :href="`#${id}`"
      :class="{ 'font-bold': activeId === id }"
    >
      {{ id }}
    </a>
  </nav>
</template>

useFileUpload

Handle file uploads.

const { files, open, reset, remove } = useFileUpload({
  accept: 'image/*',
  multiple: true,
  maxFiles: 5,
  maxSize: 5 * 1024 * 1024 // 5MB
})

// Open file picker
open()

// Files selected
files.value // FileList

// Reset selection
reset()

// Remove specific file
remove(index)

With UFileUpload

<script setup>
const { files, open, reset } = useFileUpload()
</script>

<template>
  <UFileUpload v-model="files" accept="image/*" @change="handleFiles">
    <template #default="{ dragover }">
      <div :class="{ 'border-primary': dragover }">
        Drop files here or <UButton @click="open">Browse</UButton>
      </div>
    </template>
  </UFileUpload>
</template>

defineLocale

Define/extend locale for i18n.

// locales/es.ts
export default defineLocale({
  name: 'Español',
  code: 'es',
  messages: {
    select: {
      placeholder: 'Seleccionar...',
      noResults: 'Sin resultados'
    },
    pagination: {
      previous: 'Anterior',
      next: 'Siguiente'
    }
  }
})

Extend Existing Locale

import en from '@nuxt/ui/locale/en'

export default extendLocale(en, {
  messages: {
    select: {
      placeholder: 'Choose an option...'
    }
  }
})

Use in App

<script setup>
import es from '~/locales/es'
</script>

<template>
  <UApp :locale="es">
    <NuxtPage />
  </UApp>
</template>

useFormField

Access form field context in custom components.

// Inside custom form component
const { name, error, disabled } = useFormField()

// name: field name from UFormField
// error: validation error message
// disabled: if field is disabled

Custom Input Component

<script setup>
const props = defineProps<{ modelValue: string }>()
const emit = defineEmits(['update:modelValue'])

const { error } = useFormField()
</script>

<template>
  <input
    :value="modelValue"
    :class="{ 'border-error': error }"
    @input="emit('update:modelValue', $event.target.value)"
  />
  <span v-if="error" class="text-error">{{ error }}</span>
</template>

Quick Reference