ui/docs/content/3.components/command-palette.md

title, description, links, navigation

title	description	links	navigation
CommandPalette	A command palette to search and execute commands with full-text search.	label icon to Combobox i-custom-radix-vue https://www.radix-vue.com/components/combobox.html label icon to GitHub i-simple-icons-github https://github.com/nuxt/ui/tree/v3/src/runtime/components/CommandPalette.vue	badge label Todo

Usage

Groups

Use the groups prop as an array of objects with the following properties:

• id: string{lang="ts-type"}
• label?: string{lang="ts-type"}
• slot?: string{lang="ts-type"}
• items?: CommandPaletteItem[]{lang="ts-type"}
• filter?: boolean{lang="ts-type"}
• postFilter?: (searchTerm: string, items: T[]) => T[]{lang="ts-type"}
• highlightedIcon?: string{lang="ts-type"}

::caution You must provide an id for each group otherwise the group will be ignored. ::

Items

Each group takes some items as an array of objects with the following properties:

• prefix?: string{lang="ts-type"}
• label?: string{lang="ts-type"}
• suffix?: string{lang="ts-type"}
• icon?: string{lang="ts-type"}
• avatar?: AvatarProps{lang="ts-type"}
• chip?: ChipProps{lang="ts-type"}
• kbds?: string[] | KbdProps[]{lang="ts-type"}
• disabled?: boolean{lang="ts-type"}
• slot?: string{lang="ts-type"}
• select?(e?: Event): void{lang="ts-type"}

::component-code

collapse: true ignore:

• groups
• class external:
• groups class: '!p-0' props: groups:
  • id: 'users' label: 'Users' items:
    • label: 'John Doe' suffix: 'john.doe@example.com' icon: 'i-heroicons-user'
    • label: 'Jane Doe' suffix: 'jane.doe@example.com' icon: 'i-heroicons-user'
    • label: 'John Smith' suffix: 'john.smith@example.com' icon: 'i-heroicons-user' class: 'flex-1'

---

::

Multiple

Use the multiple prop to allow multiple selections.

::component-code

collapse: true ignore:

• groups
• class external:
• groups class: '!p-0' props: multiple: true groups:
  • id: 'actions' label: 'Actions' items:
    • label: 'Add new file' suffix: 'Create a new file in the current directory or workspace.' icon: 'i-heroicons-document-plus' kbds:
      • 'meta'
      • 'N'
    • label: 'Add new folder' suffix: 'Create a new folder in the current directory or workspace.' icon: 'i-heroicons-folder-plus' kbds:
      • 'meta'
      • 'F'
    • label: 'Add hashtag' suffix: 'Add a hashtag to the current item.' icon: 'i-heroicons-hashtag' kbds:
      • 'meta'
      • 'H'
    • label: 'Add label' suffix: 'Add a label to the current item.' icon: 'i-heroicons-tag' kbds:
      • 'meta'
      • 'L' class: 'flex-1'

---

::

Placeholder

Use the placeholder prop to change the placeholder text.

::component-code

ignore:

• class class: '!p-0' props: placeholder: 'Search a user...' class: 'flex-1'

---

::

Icon

Use the icon prop to customize the input Icon. Defaults to i-heroicons-magnifying-glass-20-solid.

::component-code

ignore:

• class class: '!p-0' props: icon: 'i-heroicons-user' class: 'flex-1'

---

::

::tip{to="/getting-started/icons#theme"} You can customize this icon globally in your app.config.ts under ui.icons.search key. ::

Loading

Use the loading prop to show a loading icon on the CommandPalette.

Use the loading-icon prop to customize this icon. Defaults to i-heroicons-arrow-path-20-solid.

::component-code

ignore:

• class class: '!p-0' props: loading: true loadingIcon: '' class: 'flex-1'

---

::

::tip{to="/getting-started/icons#theme"} You can customize this icon globally in your app.config.ts under ui.icons.loading key. ::

Disabled

Use the disabled prop to disable the CommandPalette.

::component-code

ignore:

• class class: '!p-0' props: disabled: true class: 'flex-1'

---

::

Close

Use the close prop to display a Button to dismiss the CommandPalette.

::tip An update:open event will be emitted when the close button is clicked. ::

Use the close-icon prop to customize the button Icon. Defaults to i-heroicons-x-mark-20-solid.

::component-code

ignore:

• class
• close class: '!p-0' props: close: true closeIcon: '' class: 'flex-1'

---

::

::tip{to="/getting-started/icons#theme"} You can customize this icon globally in your app.config.ts under ui.icons.close key. ::

You can pass all the props of the Button component to customize it.

::component-code

prettier: true ignore:

• close.color
• close.variant
• class class: '!p-0' props: close: color: primary variant: outline class: 'rounded-full' class: 'flex-1'

---

::

Examples

Control active item(s)

You can control the active item(s) by using the default-value prop or the v-model directive with the index of the item.

::note You can also use it without any of these and either use the select field on each item and/or the @update:model-value event. ::

Control selected item(s)

Control search term

With fetched items

With filtered items

Within a modal

You can use the CommandPalette component inside a Modal's content.

::component-example

collapse: true name: 'modal-command-palette-example' class: 'justify-center'

::

Within a drawer

You can use the CommandPalette component inside a Drawer's content.

::component-example

collapse: true name: 'drawer-command-palette-example' class: 'justify-center'

::

Within a popover

You can use the CommandPalette component inside a Popover's content.

::component-example

collapse: true name: 'popover-command-palette-example' class: 'justify-center'

::

Listen open state

With custom search

With highlighted search

With custom slot

API

Props

::component-props

ignore:

• as
• to
• target
• active
• activeClass
• inactiveClass
• exactActiveClass
• ariaCurrentValue
• href
• rel
• noRel
• prefetch
• prefetchOn
• noPrefetch
• prefetchedClass
• replace
• exact
• exactQuery
• exactHash
• external

---

::

Slots

:component-slots

Emits

:component-emits

Theme

:component-theme