mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-19 06:21:46 +01:00
229 lines
6.0 KiB
Markdown
229 lines
6.0 KiB
Markdown
---
|
|
title: CommandPalette
|
|
description: Add a customizable command palette to your app.
|
|
links:
|
|
- label: GitHub
|
|
icon: i-simple-icons-github
|
|
to: https://github.com/nuxt/ui/blob/dev/src/runtime/components/navigation/CommandPalette.vue
|
|
- label: 'Combobox'
|
|
icon: i-simple-icons-headlessui
|
|
to: 'https://headlessui.com/vue/combobox'
|
|
---
|
|
|
|
## Usage
|
|
|
|
Use a `v-model` to display a searchable and selectable list of commands.
|
|
|
|
::component-example
|
|
---
|
|
padding: false
|
|
component: 'command-palette-example-basic'
|
|
componentProps:
|
|
class: 'h-[257px]'
|
|
---
|
|
::
|
|
|
|
You can put a `CommandPalette` anywhere you want but it's most commonly used inside of a modal.
|
|
|
|
:component-example{component="command-palette-example-modal"}
|
|
|
|
You can pass multiple groups of commands to the component. Each group will be separated by a divider and will display a label.
|
|
|
|
Without a `v-model`, you can also listen on `@update:model-value` to navigate to a link or do something else when a command is clicked.
|
|
|
|
::component-example
|
|
---
|
|
padding: false
|
|
component: 'command-palette-example-groups'
|
|
componentProps:
|
|
class: 'h-[274px]'
|
|
---
|
|
::
|
|
|
|
### Icon
|
|
|
|
Use any icon from [Iconify](https://icones.js.org) by setting the `icon` prop by using this pattern: `i-{collection_name}-{icon_name}`.
|
|
|
|
Use the `selected-icon` prop to set a different icon or change it globally in `ui.commandPalette.default.selectedIcon`. Defaults to `i-heroicons-check-20-solid`.
|
|
|
|
::component-card
|
|
---
|
|
padding: false
|
|
baseProps:
|
|
emptyState: null
|
|
props:
|
|
icon: 'i-heroicons-command-line'
|
|
excludedProps:
|
|
- icon
|
|
---
|
|
::
|
|
|
|
### Loading
|
|
|
|
Use the `loading` prop to show a loading icon.
|
|
|
|
Use the `loading-icon` prop to set a different icon or change it globally in `ui.commandPalette.default.loadingIcon`. Defaults to `i-heroicons-arrow-path-20-solid`.
|
|
|
|
::component-card
|
|
---
|
|
padding: false
|
|
baseProps:
|
|
emptyState: null
|
|
props:
|
|
loading: true
|
|
excludedProps:
|
|
- icon
|
|
---
|
|
::
|
|
|
|
### Placeholder
|
|
|
|
Use the `placeholder` prop to change the input placeholder
|
|
|
|
::component-card
|
|
---
|
|
padding: false
|
|
baseProps:
|
|
emptyState: null
|
|
props:
|
|
placeholder: 'Type a command...'
|
|
excludedProps:
|
|
- icon
|
|
---
|
|
::
|
|
|
|
### Close
|
|
|
|
Use the `close-button` prop to display a close button on the right side of the input.
|
|
|
|
You can pass all the props of the [Button](/elements/button) component to customize it through the `close-button` prop or globally through `ui.commandPalette.default.closeButton`.
|
|
|
|
::component-card
|
|
---
|
|
padding: false
|
|
baseProps:
|
|
emptyState: null
|
|
props:
|
|
closeButton:
|
|
icon: 'i-heroicons-x-mark-20-solid'
|
|
color: 'gray'
|
|
variant: 'link'
|
|
padded: false
|
|
excludedProps:
|
|
- closeButton
|
|
---
|
|
::
|
|
|
|
### Empty
|
|
|
|
An empty state will be displayed when there are no results.
|
|
|
|
Use the `empty-state` prop to customize the `icon` and `label` or change them globally in `ui.commandPalette.default.emptyState`.
|
|
|
|
You can also set it to `null` to hide the empty state.
|
|
|
|
::component-card
|
|
---
|
|
padding: false
|
|
baseProps:
|
|
placeholder: 'Type something to see the empty label change'
|
|
props:
|
|
emptyState:
|
|
icon: 'i-heroicons-magnifying-glass-20-solid'
|
|
label: "We couldn't find any items."
|
|
queryLabel: "We couldn't find any items with that term. Please try again."
|
|
excludedProps:
|
|
- emptyState
|
|
---
|
|
::
|
|
|
|
## Full-text search
|
|
|
|
The CommandPalette component takes care of the full-text search for you with [Fuse.js](https://fusejs.io). You can pass all the options of Fuse.js through the `fuse` prop.
|
|
|
|
When searching for a command, the component will look for a `label` property on the command by default. You can customize this behavior by overriding the `command-attribute` prop. This will also affect the display of the command.
|
|
|
|
You can also highlight the matches in the command by setting the `fuse.fuseOptions.includeMatches` to `true`. The CommandPalette component automatically takes care of the highlighting for you.
|
|
|
|
```vue
|
|
<template>
|
|
<UCommandPalette
|
|
command-attribute="title"
|
|
:fuse="{
|
|
fuseOptions: {
|
|
ignoreLocation: true,
|
|
includeMatches: true,
|
|
threshold: 0,
|
|
keys: ['title', 'description', 'children.children.value', 'children.children.children.value']
|
|
},
|
|
resultLimit: 10
|
|
}"
|
|
/>
|
|
</template>
|
|
```
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
Try it yourself in this documentation's search by pressing :kbd{value="meta"} :kbd{value="K" class="ml-1"}.
|
|
::
|
|
|
|
## Async search
|
|
|
|
You can also pass an `async` function to the `search` property of a group to perform an async search. The function will receive the query as its first argument and should return an array of commands.
|
|
|
|
::component-example
|
|
---
|
|
padding: false
|
|
component: 'command-palette-example-async'
|
|
componentProps:
|
|
class: 'h-[274px]'
|
|
---
|
|
::
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
The `loading` state will automatically be enabled when a `search` function is loading. You can disable this behavior by setting the `loading-icon` prop to `null` or globally in `ui.commandPalette.default.loadingIcon`.
|
|
::
|
|
|
|
## Slots
|
|
|
|
### `<group>-icon`
|
|
|
|
Use the `#<group>-icon` slot to override the left command content which display by default the `icon`, `avatar` and `chip`.
|
|
|
|
### `<group>-command`
|
|
|
|
Use the `#<group>-command` slot to override the command content which display by default the `prefix`, `suffix` and `label` (customizable through the `command-attribute` prop).
|
|
|
|
### `<group>-active`
|
|
|
|
Use the `#<group>-active` slot to override the right command content (when hovered) which display by default the `active` field of the group if provided.
|
|
|
|
### `<group>-inactive`
|
|
|
|
Use the `#<group>-inactive` slot to override the right command content (when not hovered) which display by default the `inactive` field of the group if provided or the `shortcuts` of the command.
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
The 4 slots above will have access to the `group`, `command`, `active` and `selected` properties in the slot scope.
|
|
::
|
|
|
|
### `empty-state`
|
|
|
|
Use the `#empty-state` slot to customize the empty state.
|
|
|
|
::component-example
|
|
---
|
|
padding: false
|
|
overflowClass: 'overflow-x-auto'
|
|
component: 'command-palette-example-empty-slot'
|
|
componentProps:
|
|
class: 'flex-1'
|
|
---
|
|
::
|
|
|
|
## Props
|
|
|
|
:component-props
|
|
|
|
## Preset
|
|
|
|
:component-preset
|