Allow controlling the highlighted/active index in Command/CommandList for advanced keyboard navigation (multiselect, async, etc.)

[johan44co]

Currently, CMDK automatically highlights the first item in the list when the dropdown opens or after a selection/removal. There is no public API to control which item is highlighted (i.e., the “active descendant” for keyboard navigation and accessibility). This leads to suboptimal UX in scenarios such as multiselect dropdowns, where users expect the highlight to remain on the next logical item after selection or removal, rather than resetting to the first item.

---

Real-World Example: Multiselect Tag Input

In our property management platform, we use a multiselect tag input built on CMDK. When a user selects or removes a tag, that option is removed from the dropdown. Currently, CMDK resets the highlight to the first item, which is disruptive for keyboard users. We want to keep the highlight on the next logical item after a selection/removal, to provide a smoother, more accessible experience. This is not possible with the current CMDK API.

Bildschirmaufnahme.2025-06-04.um.13.47.57.mov

---

Current Workarounds

• Using hidden <CommandItem />s or setting defaultValue to a non-existent value to prevent the first item from being selected by default.
• Programmatically focusing items with refs, which is brittle and not idiomatic React.
• These workarounds are not robust, can break accessibility, and are not future-proof.

---

Proposed Solution

• Expose a highlightedIndex (or activeIndex) prop on <Command> or <CommandList>, along with an onHighlightChange callback.
• This would allow consumers to:
  • Set the highlighted item programmatically (e.g., after selection, filtering, or list changes).
  • Synchronize the highlight with custom state or logic.
  • Provide a more accessible and predictable experience for keyboard users.

API Example

<Command
  highlightedIndex={highlightedIndex}
  onHighlightChange={setHighlightedIndex}
>
  {/* ... */}
</Command>

---

References

• GitHub Issue #171: First item is selected by default - can this be disabled?
• shadcn/ui#66: Multi select ?
• Downshift API for reference (Downshift exposes a controlled highlighted index for similar use cases.)

---

Benefits

• Enables advanced, accessible keyboard navigation patterns.
• Makes CMDK more flexible for complex UIs (multiselect, async search, etc.).
• Reduces the need for hacks and workarounds.
• Aligns with best practices in headless UI libraries.

---

Thank you for your work on CMDK! This feature would make the library even more powerful and accessible.

---

[Ganbin]

I say +1 because I also struggle in a different scenario.

I have a list of project that I show (All projects list), on top of the list I show the most recently selected (5 last selected projects) but I want that when I user type on the search, that the first selected is the one found in the all projects list so the user can directly hit enter when the search is successful.

Now with the current behavior it will always be the most recent project that will be selected, The user would need to navigate 5 time with the down arrow to select the one found by his search.

I struggle to find a workaround and everything seems like some hacking around.