mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 12:14:41 +01:00
844b3185e9
Co-authored-by: Pooya Parsa <pooya@pi0.io> Co-authored-by: Florent Delerue <florentdelerue@hotmail.com> Co-authored-by: Sébastien Chopin <seb@nuxt.com>
241 lines
6.4 KiB
Markdown
241 lines
6.4 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 :shortcut{value="meta"} :shortcut{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`.
|
|
::
|
|
|
|
## Filter search
|
|
|
|
You can also pass a function to the `filter` property of a group to filter displayed commands after the search happened. The function will receive the query as its first argument, the array of commands as second argument and should return an array of commands.
|
|
|
|
::component-example
|
|
---
|
|
padding: false
|
|
component: 'command-palette-example-filter'
|
|
componentProps:
|
|
class: 'h-[274px]'
|
|
---
|
|
::
|
|
|
|
## 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
|
|
component: 'command-palette-example-empty-slot'
|
|
componentProps:
|
|
class: 'flex-1'
|
|
---
|
|
::
|
|
|
|
## Props
|
|
|
|
:component-props
|
|
|
|
## Config
|
|
|
|
:component-preset
|