CommandPalette

A searchable command palette powered by Fuse.js for fast, fuzzy text search.

Usage

Use the v-model directive to control the value of the CommandPalette or the default-value prop to set the initial value when you do not need to control its state.

{
  "wait": "Loading client-side content..."
}

You can also use the @update:model-value event to listen to the selected item(s).

The CommandPalette component filters groups and ranks matching commands by relevance as users type. It provides dynamic, instant search results for efficient command discovery. Use the groups prop as an array of objects with the following properties:

id: string
label?: string
slot?: string
items?: CommandPaletteItem[]
ignoreFilter?: boolean
postFilter?: (searchTerm: string, items: T[]) => T[]
highlightedIcon?: IconComponent

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

Each group contains an items array of objects that define the commands. Each item can have the following properties:

prefix?: string
label?: string
suffix?: string
icon?: IconComponent
avatar?: AvatarProps
chip?: ChipProps
kbds?: string[] | KbdProps[]
active?: boolean
loading?: boolean
disabled?: boolean
slot?: string
placeholder?: string
children?: CommandPaletteItem[]
onSelect?: (e: Event) => void
class?: any
b24ui?: { item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLeadingChipSize?: ClassNameValue, itemLeadingChip?: ClassNameValue, itemLabel?: ClassNameValue, itemLabelPrefix?: ClassNameValue, itemLabelBase?: ClassNameValue, itemLabelSuffix?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingKbds?: ClassNameValue, itemTrailingKbdsSize?: ClassNameValue, itemTrailingHighlightedIcon?: ClassNameValue, itemTrailingIcon?: ClassNameValue }

You can pass any property from the Link component such as to, target, etc.

{
  "wait": "Loading client-side content..."
}

Each item can take a children array of objects with the following properties to create submenus:

Multiple

Use the multiple prop to allow multiple selections.

{
  "wait": "Loading client-side content..."
}

Ensure to pass an array to the default-value prop or the v-model directive.

Placeholder

Use the placeholder prop to change the placeholder text.

placeholder

{
  "wait": "Loading client-side content..."
}

Icon

Use the icon prop to customize the input Icon.

{
  "wait": "Loading client-side content..."
}

Selected Icon

Use the selected-icon prop to customize the selected item Icon.

{
  "wait": "Loading client-side content..."
}

Trailing Icon

Use the trailing-icon prop to customize the trailing Icon when an item has children.

{
  "wait": "Loading client-side content..."
}

Loading

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

{
  "wait": "Loading client-side content..."
}

Close

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

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

{
  "wait": "Loading client-side content..."
}

You can pass any property from the Button component to customize it.

{
  "wait": "Loading client-side content..."
}

Close Icon

Use the close-icon prop to customize the close button Icon.

{
  "wait": "Loading client-side content..."
}

Back

Use the back prop to customize or hide the back button (with false value) displayed when navigating into a submenu.

You can pass any property from the Button component to customize it.

{
  "wait": "Loading client-side content..."
}

Back Icon

Use the back-icon prop to customize the back button Icon.

{
  "wait": "Loading client-side content..."
}

Disabled

Use the disabled prop to disable the CommandPalette.

disabled

{
  "wait": "Loading client-side content..."
}

Examples

Control selected item(s)

You can control the selected item(s) by using the default-value prop or the v-model directive, by using the onSelect field on each item or by using the @update:model-value event.

{
  "wait": "Loading client-side content..."
}

Control search term

Use the v-model:search-term directive to control the search term.

{
  "wait": "Loading client-side content..."
}

This example uses the @update:model-value event to reset the search term when an item is selected.

With children in items

You can create hierarchical menus by using the children property in items. When an item has children, it will automatically display a chevron icon and enable navigation into a submenu.

{
  "wait": "Loading client-side content..."
}

When navigating into a submenu:

The search term is reset
A back button appears in the input
You can go back to the previous group by pressing the ⌫ key

With fetched items

You can fetch items from an API and use them in the CommandPalette.

{
  "wait": "Loading client-side content..."
}

With ignore filter

You can set the ignoreFilter field to true on a group to disable the internal search and use your own search logic.

{
  "wait": "Loading client-side content..."
}

This example uses refDebounced to debounce the API calls.

With post-filtered items

You can use the postFilter field on a group to filter items after the search happened.

{
  "wait": "Loading client-side content..."
}

Start typing to see items with higher level appear.

With custom fuse search

You can use the fuse prop to override the options of useFuse which defaults to:

{
  fuseOptions: {
    ignoreLocation: true,
    threshold: 0.1,
    keys: ['label', 'suffix']
  },
  resultLimit: 12,
  matchAllWhenSearchEmpty: true
}

The fuseOptions are the options of Fuse.js, the resultLimit is the maximum number of results to return and the matchAllWhenSearchEmpty is a boolean to match all items when the search term is empty.

You can for example set { fuseOptions: { includeMatches: true } } to highlight the search term in the items.

{
  "wait": "Loading client-side content..."
}

With virtualization

Use the virtualize prop to enable virtualization for large lists as a boolean or an object with options like { estimateSize: 32, overscan: 12 }.

When enabled, all groups are flattened into a single list due to a limitation of Reka UI.

{
  "wait": "Loading client-side content..."
}

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

{
  "wait": "Loading client-side content..."
}

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

{
  "wait": "Loading client-side content..."
}

Listen open state

When using the close prop, you can listen to the update:open event when the button is clicked.

{
  "wait": "Loading client-side content..."
}

This can be useful when using the CommandPalette inside a Modal for example.

With footer slot

Use the #footer slot to add custom content at the bottom of the CommandPalette, such as keyboard shortcuts help or additional actions.

{
  "wait": "Loading client-side content..."
}

With custom slot

Use the slot property to customize a specific item or group.

You will have access to the following slots:

#{{ item.slot }}
#{{ item.slot }}-leading
#{{ item.slot }}-label
#{{ item.slot }}-trailing
#{{ group.slot }}
#{{ group.slot }}-leading
#{{ group.slot }}-label
#{{ group.slot }}-trailing

{
  "wait": "Loading client-side content..."
}

You can also use the #item, #item-leading, #item-label and #item-trailing slots to customize all items.

API

Props

Prop	Default	Type
`as`	`'div'`	`any` The element or component this component should render as.
`icon`	`icons.search`	`IconComponent` The icon displayed in the input.
`trailingIcon`	`icons.search`	`IconComponent` The icon displayed on the right side of the input.
`selectedIcon`	`icons.check`	`IconComponent` The icon displayed when an item is selected.
`childrenIcon`	`icons.chevronRight`	`IconComponent` The icon displayed when an item has children.
`placeholder`	`t('commandPalette.placeholder')`	`string` The placeholder text for the input.
`autofocus`	`true`	`boolean` Automatically focus the input when component is mounted.
`close`	`false`	`boolean \| Partial<ButtonProps>` Display a close button in the input (useful when inside a Modal for example). `{ size: 'sm', color: 'air-tertiary-no-accent' }`
`closeIcon`	`icons.close`	`IconComponent` The icon displayed in the close button.
`back`	`true`	`boolean \| ButtonProps` Display a button to navigate back in history. `{ size: 'sm', color: 'air-selection' }`
`backIcon`	`icons.arrowLeft`	`IconComponent` The icon displayed in the back button.
`groups`		`CommandPaletteGroup<CommandPaletteItem>[]`
`fuse`	`{ fuseOptions: { ignoreLocation: true, threshold: 0.1, keys: ['label', 'suffix'] }, resultLimit: 12, matchAllWhenSearchEmpty: true }`	`UseFuseOptions<CommandPaletteItem>` Options for useFuse.
`virtualize`	`false`	`boolean \| { overscan?: number ; estimateSize?: number \| undefined; } \| undefined` Enable virtualization for large lists. Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
`labelKey`	`'label'`	`string \| number` The key used to get the label from the item.
`descriptionKey`	`'description'`	`string \| number` The key used to get the description from the item.
`preserveGroupOrder`	`false`	`boolean` Whether to preserve the order of groups as defined in the `groups` prop when filtering. When `false`, groups will appear based on item matches.
`multiple`		`boolean` Whether multiple options can be selected or not.
`disabled`		`boolean` When `true`, prevents the user from interacting with listbox
`modelValue`	`''`	`null \| string \| number \| bigint \| Record<string, any> \| AcceptableValue[]` The controlled value of the listbox. Can be binded with with `v-model`.
`defaultValue`		`null \| string \| number \| bigint \| Record<string, any> \| AcceptableValue[]` The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox
`highlightOnHover`	`true`	`boolean` When `true`, hover over item will trigger highlight
`selectionBehavior`	`'toggle'`	`"replace" \| "toggle"` How multiple selection should behave in the collection.
`loading`		`boolean` When `true`, the loading icon will be displayed.
`searchTerm`	`''`	`string`
`b24ui`		{ root?: ClassNameValue; input?: ClassNameValue; close?: ClassNameValue; back?: ClassNameValue; content?: ClassNameValue; footer?: ClassNameValue; viewport?: ClassNameValue; group?: ClassNameValue; empty?: ClassNameValue; label?: ClassNameValue; item?: ClassNameValue; itemLeadingIcon?: ClassNameValue; itemLeadingAvatar?: ClassNameValue; itemLeadingAvatarSize?: ClassNameValue; itemLeadingChip?: ClassNameValue; itemLeadingChipSize?: ClassNameValue; itemTrailing?: ClassNameValue; itemTrailingIcon?: ClassNameValue; itemTrailingHighlightedIcon?: ClassNameValue; itemTrailingKbds?: ClassNameValue; itemTrailingKbdsSize?: ClassNameValue; itemWrapper?: ClassNameValue; itemLabel?: ClassNameValue; itemDescription?: ClassNameValue; itemLabelBase?: ClassNameValue; itemLabelPrefix?: ClassNameValue; itemLabelSuffix?: ClassNameValue; }

Slots

Slot	Type
`empty`	`{ searchTerm?: string \| undefined; }`
`footer`	`{ b24ui: object; }`
`back`	`{ b24ui: object; }`
`close`	`{ b24ui: object; }`
`item`	`{ item: CommandPaletteItem; index: number; b24ui: object; }`
`item-leading`	`{ item: CommandPaletteItem; index: number; b24ui: object; }`
`item-label`	`{ item: CommandPaletteItem; index: number; b24ui: object; }`
`item-description`	`{ item: CommandPaletteItem; index: number; b24ui: object; }`
`item-trailing`	`{ item: CommandPaletteItem; index: number; b24ui: object; }`

Emits

Event	Type
`update:modelValue`	`[value: CommandPaletteItem]`
`highlight`	`[payload: { ref: HTMLElement; value: CommandPaletteItem; } \| undefined]`
`entryFocus`	`[event: CustomEvent<any>]`
`leave`	`[event: Event]`
`update:open`	`[value: boolean]`
`update:searchTerm`	`[value: string]`

Theme

app.config.ts

export default defineAppConfig({
  b24ui: {
    commandPalette: {
      slots: {
        root: 'flex flex-col min-h-0 min-w-0 divide-y divide-(--ui-color-design-tinted-na-stroke)',
        input: 'ps-[40px] pe-[44px]',
        close: '',
        back: 'p-0',
        content: 'relative overflow-hidden flex flex-col',
        footer: 'p-1',
        viewport: 'relative scroll-py-1 overflow-y-auto scrollbar-thin flex-1 focus:outline-none',
        group: 'p-1 isolate',
        empty: 'py-6 text-center text-(length:--ui-font-size-sm) text-(--b24ui-typography-description-color)',
        label: 'p-[6px] text-(length:--ui-font-size-xs) text-(--b24ui-typography-label-color)',
        item: 'group relative w-full flex items-center gap-[6px] p-[6px] text-(length:--ui-font-size-sm) select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-(--ui-border-radius-sm) data-disabled:cursor-not-allowed data-disabled:opacity-30',
        itemLeadingIcon: 'shrink-0 size-[20px]',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '2xs',
        itemLeadingChip: 'shrink-0 size-[20px]',
        itemLeadingChipSize: 'md',
        itemTrailing: 'ms-auto inline-flex gap-[6px] items-center',
        itemTrailingIcon: 'shrink-0 size-[20px] text-(--ui-color-accent-main-primary)',
        itemTrailingHighlightedIcon: 'shrink-0 size-[20px] text-(--b24ui-typography-label-color) hidden group-data-highlighted:inline-flex',
        itemTrailingKbds: 'hidden lg:inline-flex items-center shrink-0 gap-0.5',
        itemTrailingKbdsSize: 'md',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0 overflow-hidden',
        itemLabel: 'truncate space-x-1 text-(--b24ui-typography-label-color)',
        itemDescription: 'truncate -mt-[6px] text-(--b24ui-typography-description-color) text-(length:--ui-font-size-sm)',
        itemLabelBase: 'text-(--b24ui-typography-label-color) [&>mark]:text-(--ui-color-black-base) [&>mark]:bg-(--ui-color-collab-accent-less-1)',
        itemLabelPrefix: 'text-(--b24ui-typography-legend-color)',
        itemLabelSuffix: 'truncate text-(--b24ui-typography-description-color) [&>mark]:text-(--ui-color-black-base) [&>mark]:bg-(--ui-color-collab-accent-less-1)'
      },
      variants: {
        virtualize: {
          true: {
            viewport: 'p-1 isolate'
          },
          false: {
            viewport: ''
          }
        },
        active: {
          true: {
            item: 'text-(--b24ui-typography-label-color) before:bg-(--ui-color-base-8)',
            itemLeadingIcon: 'text-(--b24ui-typography-legend-color)'
          },
          false: {
            item: 'text-(--b24ui-typography-legend-color) data-highlighted:not-data-disabled:text-(--b24ui-typography-legend-color) data-highlighted:not-data-disabled:before:bg-(--ui-color-bg-content-secondary) transition-colors before:transition-colors',
            itemLeadingIcon: 'text-(--b24ui-typography-legend-color) group-data-highlighted:not-group-data-disabled:text-(--b24ui-typography-legend-color) transition-colors'
          }
        },
        loading: {
          true: {
            itemLeadingIcon: 'animate-spin'
          }
        }
      }
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      b24ui: {
        commandPalette: {
          slots: {
            root: 'flex flex-col min-h-0 min-w-0 divide-y divide-(--ui-color-design-tinted-na-stroke)',
            input: 'ps-[40px] pe-[44px]',
            close: '',
            back: 'p-0',
            content: 'relative overflow-hidden flex flex-col',
            footer: 'p-1',
            viewport: 'relative scroll-py-1 overflow-y-auto scrollbar-thin flex-1 focus:outline-none',
            group: 'p-1 isolate',
            empty: 'py-6 text-center text-(length:--ui-font-size-sm) text-(--b24ui-typography-description-color)',
            label: 'p-[6px] text-(length:--ui-font-size-xs) text-(--b24ui-typography-label-color)',
            item: 'group relative w-full flex items-center gap-[6px] p-[6px] text-(length:--ui-font-size-sm) select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-(--ui-border-radius-sm) data-disabled:cursor-not-allowed data-disabled:opacity-30',
            itemLeadingIcon: 'shrink-0 size-[20px]',
            itemLeadingAvatar: 'shrink-0',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'shrink-0 size-[20px]',
            itemLeadingChipSize: 'md',
            itemTrailing: 'ms-auto inline-flex gap-[6px] items-center',
            itemTrailingIcon: 'shrink-0 size-[20px] text-(--ui-color-accent-main-primary)',
            itemTrailingHighlightedIcon: 'shrink-0 size-[20px] text-(--b24ui-typography-label-color) hidden group-data-highlighted:inline-flex',
            itemTrailingKbds: 'hidden lg:inline-flex items-center shrink-0 gap-0.5',
            itemTrailingKbdsSize: 'md',
            itemWrapper: 'flex-1 flex flex-col text-start min-w-0 overflow-hidden',
            itemLabel: 'truncate space-x-1 text-(--b24ui-typography-label-color)',
            itemDescription: 'truncate -mt-[6px] text-(--b24ui-typography-description-color) text-(length:--ui-font-size-sm)',
            itemLabelBase: 'text-(--b24ui-typography-label-color) [&>mark]:text-(--ui-color-black-base) [&>mark]:bg-(--ui-color-collab-accent-less-1)',
            itemLabelPrefix: 'text-(--b24ui-typography-legend-color)',
            itemLabelSuffix: 'truncate text-(--b24ui-typography-description-color) [&>mark]:text-(--ui-color-black-base) [&>mark]:bg-(--ui-color-collab-accent-less-1)'
          },
          variants: {
            virtualize: {
              true: {
                viewport: 'p-1 isolate'
              },
              false: {
                viewport: ''
              }
            },
            active: {
              true: {
                item: 'text-(--b24ui-typography-label-color) before:bg-(--ui-color-base-8)',
                itemLeadingIcon: 'text-(--b24ui-typography-legend-color)'
              },
              false: {
                item: 'text-(--b24ui-typography-legend-color) data-highlighted:not-data-disabled:text-(--b24ui-typography-legend-color) data-highlighted:not-data-disabled:before:bg-(--ui-color-bg-content-secondary) transition-colors before:transition-colors',
                itemLeadingIcon: 'text-(--b24ui-typography-legend-color) group-data-highlighted:not-group-data-disabled:text-(--b24ui-typography-legend-color) transition-colors'
              }
            },
            loading: {
              true: {
                itemLeadingIcon: 'animate-spin'
              }
            }
          }
        }
      }
    })
  ]
})

Breadcrumb

A breadcrumb navigation component.

Link

A wrapper around <NuxtLink> with extra props.