Combobox Global Shortcut Focus

ProNew

A picker that opens from a keyboard shortcut anywhere on the page (Ctrl or Cmd+K), shows the shortcut as a hint on the button and returns focus to where you were when you close it with Escape. Use this when one picker is the main way to move around an app.

Customize

Derived from this item’s props table, because it declares no controls of its own. This item has no standalone playground, so changes update the code, the share link and the AI prompt.

value

defaultValue

shortcutKey

allowInInputs

aria-label

Guide and examples

When to use it

Use it for project, workspace or record switchers that experienced users reach with the keyboard, where losing your place in the page when the list closes would be frustrating.

Do not use it when the shortcut would clash with the browser or another widget. Pass a different key.

Installation

This item is part of tealmac UI Pro

The source for this item installs with a Pro licence key. Log in with your key to see the install command, or read the Pro setup page.

Props

Prop	Type	Default	Description
`options`	`{ value, label }[]`	-	The choices.
`value`	`string`	-	Selected value (controlled).
`defaultValue`	`string`	-	Initial value.
`onValueChange`	`(value: string) => void`	-	Runs when a value is chosen.
`shortcutKey`	`string`	`k`	The key used with Ctrl or Cmd.
`allowInInputs`	`boolean`	`false`	Fire while typing in a text field.
`aria-label`	`string`	`Project`	Names the picker.

Accessibility

aria-keyshortcuts="Control+K Meta+K" is on the button; the visible hint reads Ctrl K or ⌘K depending on the platform and is aria-hidden (the shortcut is also in the name).
The shortcut is ignored when focus is in an editable field (unless allowInInputs), when another dialog or menu is open, and when the key is held down (repeat).
Opening remembers the focused element; Escape returns focus to it, while choosing moves focus to the button.
The list is otherwise the normal cmdk combobox.

Testing

The pattern ships with a Testing Library test (combobox-global-shortcut-focus.test.tsx) that covers opening from anywhere, ignoring editable fields, restoring focus on Escape and choosing.