policy-ui/.claude/skills/nuxt-ui/references/composables.md

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

Key	Meaning
meta	Cmd (Mac) / Ctrl (Windows)
ctrl	Ctrl key
alt	Alt / Option key
shift	Shift key
_	Key separator

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

Composable	Purpose
useToast	Show notifications
useOverlay	Programmatic modals/slidelovers
defineShortcuts	Keyboard shortcuts
useKbd	Keyboard state detection
useScrollspy	Track scroll for TOC
useFileUpload	File upload handling
defineLocale	i18n locale definition
extendLocale	Extend existing locale
useFormField	Form field context
extractShortcuts	Parse shortcut definitions