⌘K-sv

A port of cmdk, to Svelte.

⌘K-sv is a command menu Svelte component that can also be used as an accessible combobox. You render items, it filters and sorts them automatically.

Demo and examples: cmdk-sv.com

Install

npm install cmdk-sv

Use

	
	
		No results found.

		
			a
			b
			
			c
		

		Apple
	

Or in a dialog:

	
	
		No results found.

		
			a
			b
			
			c
		

		Apple
	

Styling

Each part has a specific data-attribute (starting with data-cmdk-) that can be used for styling.

Command [cmdk-root]

Render this to show the command menu inline, or use Dialog to render in a elevated context. Can be controlled by binding to the value prop.

	
	
		Orange
		Apple
	

By default, this uses a scoring algorithm to filter and rank items based on the user's search input. The algorithm takes into account various factors like continuous matches, word and character jumps among other things.

You can provide a custom filter function that is called to rank each item. Both strings are normalized as lowercase and trimmed.

The following example implements a strict substring match:

 {
		if (value.includes(search)) return 1;
		return 0;
	}}
/>

In this strict substring match example, the filter function returns a score of 1 if the item's value contains the search string as a substring, and 0 otherwise, removing it from the result list.

Or disable filtering and sorting entirely:

	
		{#each filteredItems as item}
			
				{item}
			
		{/each}
	

You can make the arrow keys wrap around the list (when you reach the end, it goes back to the first item) by setting the loop prop:

This component also exposes two additional slot props for state (the current reactive value of the command state) and stateStore (the underlying writable state store). These can be used to implement more advanced use cases, such as debouncing the search updates with the stateStore.updateState method:

	{@const handleUpdateState = debounce(stateStore.updateState, 200)}
	

Dialog [cmdk-dialog] [cmdk-overlay]

Props are forwarded to Command. Composes Bits UI's Dialog component. The overlay is always rendered. See the Bits Documentation for more information. Can be controlled by binding to the open prop.

You can provide a portal prop that accepts an HTML element that is forwarded to Bits UI's Dialog Portal component to specify which element the Dialog should portal into (defaults to body). To disable portalling, pass null as the portal prop.

Input [cmdk-input]

All props are forwarded to the underlying input element. Can be controlled as a normal input by binding to its value prop.

List [cmdk-list]

Contains items and groups. Animate height using the --cmdk-list-height CSS variable.

[data-cmdk-list] {
	min-height: 300px;
	height: var(--cmdk-list-height);
	max-height: 500px;
	transition: height 100ms ease;
}

To scroll item into view earlier near the edges of the viewport, use scroll-padding:

[data-cmdk-list] {
	scroll-padding-block-start: 8px;
	scroll-padding-block-end: 8px;
}

Item [cmdk-item] [data-disabled?] [data-selected?]

Item that becomes active on pointer enter. You should provide a unique value for each item, but it will be automatically inferred from the .textContent if you don't. Text content is normalized as lowercase and trimmed.

 {
		console.log('Selected', value);
		// Value is implicity "apple" because of the provided text content
	}}
>
	Apple

You can force an item to always render, regardless of filtering, by passing the alwaysRender prop.

Group [cmdk-group] [hidden?]

Groups items together with the given heading ([cmdk-group-heading]).

	Apple

Groups will not be removed from the DOM, rather the hidden attribute is applied to hide it from view. This may be relevant in your styling.

You can force a group to always be visible, regardless of filtering, by passing the alwaysRender prop.

Separator [cmdk-separator]

Visible when the search query is empty or alwaysRender is true, hidden otherwise.

Empty [cmdk-empty]

Automatically renders when there are no results for the search query.

Loading [cmdk-loading]

You should conditionally render this with progress while loading asynchronous items.

	{#if loading}
		Loading…
	{/if}
;

createState(initialState?: State)

Create a state store which can be passed and used by the component. This is provided for more advanced use cases and should not be commonly used.

A good use case would be to render a more detailed empty state, like so:

	
		{#if $state.search}
			No results found for "{state.search}".
		{:else}
			No results found.
		{/if}
	

Examples

Code snippets for common use cases.

Nested items

Often selecting one item should navigate deeper, with a more refined set of items. For example selecting "Change theme…" should show new items "Dark theme" and "Light theme". We call these sets of items "pages", and they can be implemented with simple state:

 {
		// Escape goes to previous page
		// Backspace goes to previous page when search is empty
		if (e.key === 'Escape' || (e.key === 'Backspace' && !search)) {
			e.preventDefault();
			const newPages = pages.slice(0, -1);
			pages = newPages;
		}
	}}
>
	
	
		{#if !page}
			 changePage('projects')}>Search projects…
			 changePage('teams')}>Join a team…
		{:else if page === 'projects'}
			Project A
			Project B
		{:else if page === 'teams'}
			Team 1
			Team 2
		{/if}
	

Show sub-items when searching

If your items have nested sub-items that you only want to reveal when searching, render based on the search state:

{#if search}
	
		
	
{/if}

Using the state store:

	
	
		Change theme…
		Change theme to dark
		Change theme to light
	

or

Using the input value:

	
	
		Change theme…
		Change theme to dark
		Change theme to light
	

Asynchronous results

Render the items as they become available. Filtering and sorting will happen automatically.

	
	
		{#if loading}
			Fetching words…
		{:else}
			{#each items as item}
				
					{item}
				
			{/each}
		{/if}
	

Use inside Popover

We recommend using the Bits UI popover component. ⌘K-sv relies on the Bits UI Dialog component, so this will reduce the number of dependencies you'll need.

npm install bits-ui

Render Command inside of the popover content:

	Toggle popover

	
		
			
			
				Apple
			
		
	

Drop in stylesheets

You can find global stylesheets to drop in as a starting point for styling. See src/styles/cmdk for examples.

Render Delegation

Each of the components (except the dialog) accept an asChild prop that can be used to render a custom element in place of the default. When using this prop, you'll need to check the components slot props to see what attributes & actions you'll need to pass to your custom element.

Components that contain only a single element will just have attrs & action slot props, or just attrs. Components that contain multiple elements will have an attrs and possibly an actions object whose properties are the attributes and actions for each element.

FAQ

Accessible? Yes. Labeling, aria attributes, and DOM ordering tested with Voice Over and Chrome DevTools. Dialog composes an accessible Dialog implementation.

Filter/sort items manually? Yes. Pass shouldFilter={false} to Command. Better memory usage and performance. Bring your own virtualization this way.

Unstyled? Yes, use the listed CSS selectors.

Weird/wrong behavior? Make sure your Command.Item has a unique value.

Listen for ⌘K automatically? No, do it yourself to have full control over keybind context.

History

Written in 2019 by Paco (@pacocoursey) to see if a composable combobox API was possible. Used for the Vercel command menu and autocomplete by Rauno (@raunofreiberg) in 2020. Re-written independently in 2022 with a simpler and more performant approach. Ideas and help from Shu (@shuding_).

Ported to Svelte in 2023 by Huntabyte (@huntabyte)

Sponsors

This project is supported by the following beautiful people/organizations:

License

Published under the MIT license. Made by @huntabyte and community 💛