Navegação
VCommandPalette
Superfície universal de busca de comandos: encontrar conteúdo, executar ações e navegar pelo app a partir de um único lugar. Rápida, versátil e **keyboard-first**.
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
</script>Uso
<script setup lang="ts">
</script>
<template>
</template>Playground
Os controles abaixo são gerados a partir das props declaradas em VCommandPalette.types.ts; o código acompanha cada mudança.
Exemplos
Variantes, tamanhos e estados, extraídos das stories da biblioteca.
Default
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'global-search',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Quick Actions
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'quick-actions',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>File Switcher
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'file-switcher',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Settings Palette
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'settings-palette',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Small
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'sm',
variant: 'global-search',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Large
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'lg',
variant: 'global-search',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Closed
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: false,
size: 'md',
variant: 'global-search',
placeholder: 'Search for anything…'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Loading
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'global-search',
placeholder: 'Search for anything…',
loading: true
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Empty
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'global-search',
placeholder: 'Search for anything…',
query: 'zzzz-no-match'
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Disabled
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
const args = {
modelValue: true,
size: 'md',
variant: 'global-search',
placeholder: 'Search for anything…',
disabled: true
}
</script>
<template>
<div class="stage" style="position:relative;min-height:520px;"><VCommandPalette v-bind="args" /></div>
</template>Variants
Variação Variantes.
Ver código
<script setup lang="ts">
import { VCommandPalette } from 'vueui-nova-kit'
</script>
<template>
<div style="display:grid;gap:24px;">
<div class="stage" style="position:relative;min-height:420px;"><VCommandPalette data-variant="global-search" model-value /></div>
<div class="stage" style="position:relative;min-height:420px;"><VCommandPalette data-variant="quick-actions" variant="quick-actions" model-value /></div>
<div class="stage" style="position:relative;min-height:420px;"><VCommandPalette data-variant="file-switcher" variant="file-switcher" model-value /></div>
<div class="stage" style="position:relative;min-height:420px;"><VCommandPalette data-variant="settings-palette" variant="settings-palette" model-value /></div>
</div>
</template>Interactive
Variação Interativo. Interativo: o estado é mantido na própria story (v-model).
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VButton, VCommandPalette } from 'vueui-nova-kit'
const isOpen = ref(false)
const lastSelection = ref('')
</script>
<template>
<VButton data-test-id="command-palette-trigger-open" @click="isOpen = true">Open palette</VButton>
<p v-if="lastSelection">Selected: {{ lastSelection }}</p>
<div class="stage" style="position:relative;min-height:520px;margin-top:16px;">
<VCommandPalette
v-model="isOpen"
@select="(item) => { lastSelection = item.label; isOpen = false }" />
</div>
</template>Empty State Texts
Variação Vazio estado Texts. Props: modelValue=true, query="zzzz", emptyTitle="Nada encontrado", emptyHint="Tente outro termo".
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VCommandPalette } from 'vueui-nova-kit'
const value = ref(true)
const items = []
</script>
<template>
<VCommandPalette
v-model="value"
placeholder="Search for anything…"
query="zzzz"
empty-title="Nada encontrado"
empty-hint="Tente outro termo"
:items="items" />
</template>Not Dismissible
Variação Not Dismissible. Props: modelValue=true, dismissible=false.
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VCommandPalette } from 'vueui-nova-kit'
const value = ref(true)
</script>
<template>
<VCommandPalette
v-model="value"
placeholder="Search for anything…"
:dismissible="false" />
</template>Shortcut Label
Variação Shortcut rótulo. Props: modelValue=true, shortcutLabel="Ctrl K".
Ver código
<script setup lang="ts">
import { ref } from 'vue'
import { VCommandPalette } from 'vueui-nova-kit'
const value = ref(true)
</script>
<template>
<VCommandPalette
v-model="value"
placeholder="Search for anything…"
shortcut-label="Ctrl K" />
</template>Acessibilidade
Checklist unificada (doc + guia, 9–10 itens):
role="dialog"comaria-expanded(guia: 'Uses role="dialog" with
aria-expanded').
- Label acessível do input de busca.
- Navegação completa por teclado (Arrow keys, Enter, Escape).
- Enter seleciona, Escape fecha.
- Indicadores de foco claros/visíveis.
- Anuncia contagem de resultados e empty state (live regions / ARIA).
- Suporta regiões ARIA; semântica de grupos e labels descritivos.
- Alto contraste e
prefers-reduced-motion. - "Follows WAI-ARIA best practices" (doc) / "ARIA compliant
(aria-expanded, role='dialog')" (guia).
- Grupo com
role="group"+aria-labelledby; inputtype="search"ou
combobox com aria-controls/aria-activedescendant.
Estados
Closed · Hover result · Focus input · Selected result · Loading · Empty
Motion
| Trigger | Property | Duration | Easing |
|---|---|---|---|
| Open/Close | opacity/transform | 160ms | ease-out |
| Result highlight | background/color | 100ms | standard |
| Input focus | box-shadow | 100ms | ease-out |
Respeitar prefers-reduced-motion.
Todas as transições respeitam prefers-reduced-motion e os tokens --v-duration-*.
Props
| Prop | Tipo | Default | Descrição |
|---|---|---|---|
modelValue | boolean | undefined | Controlled visibility (`v-model`). |
open | boolean | undefined | Alias for `v-model:open`. |
query | string | undefined | Search query (`v-model:query`). |
placeholder | string | undefined | — |
items | VCommandPaletteGroup[] | undefined | — |
loading | boolean | false | — |
disabled | boolean | false | — |
dismissible | boolean | true | — |
size | VCommandPaletteSize | "md" | — |
variant | VCommandPaletteVariant | "global-search" | — |
shortcutLabel | string | "⌘K" | — |
emptyTitle | string | "No results found" | — |
emptyHint | string | "Try a different search term." | — |
searchLabel | string | "Search commands" | — |
ariaLabel | string | undefined | — |
Events
| Evento | Payload | Descrição |
|---|---|---|
@update:modelValue | value: boolean | — |
@update:open | value: boolean | — |
@update:query | value: string | — |
@open-change | value: boolean | — |
@select | item: VCommandPaletteItem | — |
@close | — | — |
@dismiss | — | — |
Slots
| Slot | Props do slot |
|---|---|
#trigger | — |
Fonte: src/components/navigation/VCommandPalette/VCommandPalette.vue · tipos: src/components/navigation/VCommandPalette/VCommandPalette.types.ts