Combobox

When to use

• To pick one option from a long list where typing is faster than scrolling: an exercise, a food, a client, a program template.
• When coaches know roughly what they're looking for and can type part of the name ("dead", "row").

When not to use

• About 5 to 15 options: use a Select. It needs no typing and works the same on every device.
• 2 to 4 options that should all be visible: use a Radio group.
• To run actions or jump to pages: use a Command menu.
• To browse the exercise library with filters, video previews and multi-select: that is the Exercise picker, which builds on this.

Anatomy

A combobox is a composition, not a single component. It is a Popover whose content is a Command, as in shadcn's combobox recipe. Open the example above to see the popover's parts: a search field at the top, group headings ("Lower body"), options with a check on the chosen one, and an empty message when nothing matches. The popover is as wide as the trigger.

Variants

One style. Adapt it with what the list needs:

• Grouped: CommandGroup with a heading, as in the example. Use groups only when coaches think in those groups (muscle area, meal type).
• Single choice: choosing an option closes the popover and puts its label in the trigger. Choosing the same option again clears it.
• Several choices: keep the popover open on select and show the choices as badges under the trigger. This is how the Exercise picker adds several exercises at once.

States

Usage guidelines

• Match anywhere in the name, not only the start: "dead" finds "Romanian deadlift". cmdk does this by default.
• Search the label the coach sees. Pass the visible label as the item's value, so English and Arabic names are both searchable in their own language.
• Keep the chosen value visible in the trigger. Don't clear it when the popover opens.
• Lists longer than a few hundred items should load results as the coach types, with a loading line in the list.

Content guidelines

• Label: a short noun, sentence case: "Exercise", "Food", "Assign to client".
• Trigger placeholder: an instruction, "Choose an exercise". Search placeholder: "Search exercises…", with an ellipsis.
• Options: the name as coaches say it ("Barbell back squat"), not codes or IDs. Put detail such as equipment in a second line, not in brackets.
• Empty message: say what happened and what to do: "No exercise matches. Check the spelling."
• Arabic exercise names are the ones Gulf coaches use in the gym. Keep common English loan words such as "سكوات" where that is what coaches say.

Accessibility

• The trigger is a button with role="combobox" and aria-expanded. It is labelled by the label and its current value (aria-labelledby lists both ids), so a screen reader announces "Exercise Romanian deadlift, combobox, collapsed".
• The search field is a combobox with aria-autocomplete="list", controlling a listbox of options. Name the field with Command's label prop and the list with CommandList's label prop; without them, the field has no name and the list is called "Suggestions" in English, also on Arabic screens.
• The highlighted option is set with aria-activedescendant, so focus stays in the search field while the screen reader reads each highlighted option: "Romanian deadlift".
• aria-selected marks the highlighted option, not the chosen one; the chosen value is announced from the trigger.
• The empty message is not a live region, so screen readers don't announce it on their own. Keep it short so it is quick to find with the reading cursor.

RTL

• The chevron sits at the end of the trigger and the check at the end of each option (ms-auto), so both move to the left.
• The popover aligns to the trigger's start edge (align="start"), which is its right edge in RTL.
• The search icon stays at the start of the field, on the right.
• Typing Arabic filters Arabic labels; Latin brand names inside Arabic labels stay left to right on their own.

Tokens used

Read from components/ui/command.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Opacityopacity-(--opacity-disabled)
• Radiusrounded-md
• Radiusrounded-sm
• Typefont-medium
• Typetext-sm
• Typetracking-wide
• Typetext-xs

Popover

Read from components/ui/popover.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Layerz-(--z-popover)
• Radiusrounded-md
• Shadowshadow-md
• Typefont-medium
• Typetext-sm

Props

The combobox has no component of its own: these are the Command parts it uses. See Popover for Popover, PopoverTrigger and PopoverContent.

Replaces in coach-admin

Related

Select, Command, Popover, Exercise picker, Form.