The useSearchableRoutes composable scans your application's routes and generates searchable items for use in command palettes. It automatically filters routes based on metadata, user permissions, and layout configuration.

Basic Usage

<script setup lang="ts">
const searchableRoutes = useSearchableRoutes()

// Returns computed array of CommandPaletteItem objects
// Each item has: label, icon, to, active
</script>

<template>
  <UCommandPalette
    :groups="[{ items: searchableRoutes }]"
  />
</template>

Return Value

Returns a computed ref containing an array of CommandPaletteItem objects, sorted alphabetically by label.

Each item includes:

• label - Human-readable route name (from meta.search.label or auto-generated from path)
• icon - Icon string (from meta.search.icon or defaults to i-lucide-file)
• to - Route path for navigation
• active - Always false (for command palette compatibility)

Route Filtering

Routes are automatically filtered based on:

1. Layout - Only includes routes using the default layout (excludes blank and other layouts)
2. Dynamic Routes - Excludes routes with dynamic segments (containing :)
3. Search Flag - Respects meta.search: false to explicitly hide routes
4. Permissions - Hides admin routes from non-admin users
5. Path Validity - Requires routes to have both a path and name

Route Configuration

Add search metadata to your pages to customize how they appear:

<script setup lang="ts">
definePageMeta({
  search: {
    label: 'Profile Settings',
    icon: 'i-lucide-user',
  },
})
</script>

To hide a route from search:

definePageMeta({
  search: false,
})

Auto-Generated Labels

When meta.search.label is not provided, labels are automatically generated from the route path:

• /app/settings → "Settings"
• /app/account/profile → "Account / Profile"
• /app/admin/users → "Admin / Users"

The generator:

• Removes app and admin prefixes
• Converts kebab-case to Title Case
• Joins nested segments with /

Examples

Command Palette Integration

<script setup lang="ts">
const searchableRoutes = useSearchableRoutes()

const groups = computed(() => [
  {
    key: 'pages',
    label: 'Pages',
    items: searchableRoutes.value,
  },
  {
    key: 'actions',
    label: 'Actions',
    items: customActions.value,
  },
])
</script>

<template>
  <UCommandPalette :groups="groups" />
</template>

Filtered Routes by Section

const searchableRoutes = useSearchableRoutes()

// Filter to specific sections
const settingsRoutes = computed(() =>
  searchableRoutes.value.filter(r => r.to.startsWith('/app/settings'))
)

const accountRoutes = computed(() =>
  searchableRoutes.value.filter(r => r.to.startsWith('/app/account'))
)

Notes

• Console warns when routes lack custom search icons (defaults to i-lucide-file)
• Admin routes check isAdminRoute() helper and current user role
• Routes without meaningful labels (like parent route containers) are excluded
• Requires default layout - routes with any other layout are filtered out