[Feature] Combobox: match shadcn (Base UI + vega)
Rewrites Combobox to follow shadcn's Base UI combobox with the vega style. This is a breaking change: the parts and their names change, and the old API has no aliases.
The audit on main found the old structure far from shadcn (radio buttons inside the list, a bordered popover with no animation, a search row with a magnifier icon). It also found focus that stayed on the trigger after opening, so the arrow keys did nothing until you clicked the search field, an invalid role="popover", and a role=combobox wrapper with no aria-expanded. ComboboxInputTrigger, ComboboxBadgeTrigger, ComboboxBadge and ComboboxClearButton shipped without the controller code they call, so they never worked.
Migration
| Before | After |
|---|---|
Combobox(term:, placement:) | Combobox(name:, multiple:, term:, disabled:, required:); placement moves to ComboboxContent(side:, align:, side_offset:, align_offset:) |
ComboboxTrigger(placeholder: "...") | ComboboxTrigger { ComboboxValue(placeholder: "...") } |
ComboboxPopover | ComboboxContent |
ComboboxSearchInput(placeholder:) | ComboboxInput(placeholder:, show_trigger: false) inside ComboboxContent |
ComboboxEmptyState | ComboboxEmpty |
ComboboxListGroup(label: "Fruits") | ComboboxGroup { ComboboxLabel { "Fruits" } ... }, plus ComboboxSeparator |
ComboboxItem { ComboboxRadio(name:, value:); span { "Apple" } } | ComboboxItem(value: "apple") { "Apple" } (name comes from the root) |
ComboboxCheckbox | Combobox(multiple: true) makes every item a checkbox |
CheckboxGroup(required: true) around the items | Combobox(multiple: true, required: true) |
ComboboxToggleAllCheckbox | ComboboxToggleAll { "Select all" } |
ComboboxInputTrigger | ComboboxInput(placeholder:, show_clear:) outside the content |
ComboboxBadgeTrigger, ComboboxBadge, ComboboxClearButton | ComboboxChips(max:) { ComboboxChipsInput } |
Each item still holds a native radio or checkbox (visually hidden, out of the tab order), so forms submit the selection as before and required: and FormField keep working. FormField's aria-invalid and aria-describedby are copied onto the input or trigger people see. The hidden inputs are the one structural difference from Base UI.
Three extras have no shadcn counterpart: ComboboxToggleAll (works with chips and in a popup), term: ("4 fruits" instead of every name) and ComboboxChips(max:), which collapses the chips into one "100 frameworks" chip past the cap. All four differences are registered in audit/divergences/combobox.yml.
The controller follows the APG combobox pattern like Base UI: focus stays in the input, the active option goes through aria-activedescendant, the selected item is highlighted on open, Home and End jump to the ends, Escape and outside clicks return focus to the trigger, and the popup fades and zooms in and out over 100 ms. The popup is a popover="manual" element (top layer) positioned by Floating UI; with popover="auto", clicking the input that opens it would close it.
Combobox now depends on Button (dependencies.yml). The Form docs example and the MCP registry are updated. A Codex review raised nine issues (multiple required: ignored, errors only on the hidden inputs, Clear out of the tab order, chevron focus, Turbo morph state and ids, disabled items removed by Backspace, two listener/highlight leaks); all are fixed here.
Screenshots
Audit fixture: shadcn's "Combobox in Popup" example, 1280×800, same strings on both sides.




Test steps
cd gem && bundle exec rake(tests and standardrb).cd docs && bin/dev, open/docs/combobox:- Basic: click the input, type "re", press ArrowDown and Enter. The input shows "Remix" and the popup closes. The chevron opens it with focus in the input.
- With clear button: the × clears the value; Tab from the input reaches it.
- With groups: type "carr". The Fruits group hides; type more for the empty message.
- Disabled items: ArrowDown skips SvelteKit and Remix.
- In a popup: open, use the arrows, Home/End, Enter, Escape. Focus goes back to the button.
- Multiple: pick items, remove chips with × and with Backspace.
- Select all: select all, the chips collapse into "5 frameworks"; its × clears everything.
- Multiple in a popup: "Select all", then deselect one; the trigger reads "3 fruits".
- Form: submit empty. Both fields turn red with "Pick a framework" and "Pick at least one".
/docs/form: the Combobox example validates as required.- Optional:
/shadcn-audit worktree/comboboxreproduces the checklist below.
shadcn audit on main (before)
shadcn audit ruby-ui/ruby_ui
base 7e65e61f head 7e65e61f shadcn 4aaea19d
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme neutral tokens match shadcn
Combobox (ref: bases/base/ui/combobox.tsx + style-vega.css @ 4aaea19d)
❌ Look background-color: oklch(0.145 0 0); background-color: oklch(0.269 0 0); border-bottom-color: oklch(0.922 0 0); border-left-color: oklch(0.922 0 0); border-right-color: oklch(0.922 0 0); border-top-color: oklch(0.922 0 0); box-shadow: none; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklch(0.145 0 0) 0px 0px 0px 2px, oklch(0.556 0 0) 0px 0px 0px 4px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklch(1 0 0) 0px 0px 0px 2px, oklch(0.708 0 0) 0px 0px 0px 4px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; color: oklch(0.205 0 0); column-gap: normal; display: flex; gap: normal; padding-bottom: 8px; padding-left: 16px; padding-right: 16px; padding-top: 8px; row-gap: normal
vega: background-color: oklab(1 0 0 / 0.045); background-color: oklab(1 0 0 / 0.075); border-bottom-color: oklch(0.708 0 0); border-left-color: oklch(0.708 0 0); border-right-color: oklch(0.708 0 0); border-top-color: oklch(0.708 0 0); box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.556 0 0 / 0.5) 0px 0px 0px 3px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.708 0 0 / 0.5) 0px 0px 0px 3px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; color: oklch(0.145 0 0); column-gap: 6px; display: inline-flex; gap: 6px; padding-bottom: 0px; padding-left: 10px; padding-right: 10px; padding-top: 0px; row-gap: 6px
ComboboxTrigger — closed/light, open/light, focus/light, after-esc/light, closed/dark, open/dark, focus/dark, after-esc/dark — RubyUI: border border-input bg-background px-4 h-9 hover:bg-accent, focus ring-2 ring-offset-2. shadcn renders it as Button variant=outline (vega cn-button outline: border-border bg-background dark:bg-input/30 shadow-xs px-2.5, focus-visible:ring-3 ring-ring/50), w-64 justify-between font-normal. Requested: render via Button(variant: :outline) + justify-between font-normal.
↳ computed styles (shadcn-audit collect)
❌ Look background-color: oklch(0.145 0 0); border-bottom-left-radius: 10px; border-bottom-right-radius: 10px; border-bottom-width: 1px; border-left-width: 1px; border-right-width: 1px; border-top-left-radius: 10px; border-top-right-radius: 10px; border-top-width: 1px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.1) 0px 10px 15px -3px, rgba(0, 0, 0, 0.1) 0px 4p…; color: rgb(0, 0, 0)
vega: background-color: oklch(0.205 0 0); border-bottom-left-radius: 8px; border-bottom-right-radius: 8px; border-bottom-width: 0px; border-left-width: 0px; border-right-width: 0px; border-top-left-radius: 8px; border-top-right-radius: 8px; border-top-width: 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.145 0 0 / 0.1) 0px 0px 0px 1px, rgba(0, 0, 0, 0.1) 0px 4px 6px -1px, rgba(0, 0, 0, 0.1) 0p…; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.985 0 0 / 0.1) 0px 0px 0px 1px, rgba(0, 0, 0, 0.1) 0px 4px 6px -1px, rgba(0, 0, 0, 0.1) 0p…; color: oklch(0.145 0 0); color: oklch(0.985 0 0)
ComboboxPopover — open/light, open/dark — RubyUI: border bg-background shadow-lg rounded-lg, no padding. shadcn cn-combobox-content: bg-popover ring-1 ring-foreground/10 shadow-md rounded-md max-h-72 min-w-36, width = anchor + spacing(7) (style-vega.css:296). Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
↳ computed styles (shadcn-audit collect)
❌ Look border-bottom-color: oklch(0.551 0.027 264.364); border-bottom-left-radius: 8px; border-bottom-right-radius: 8px; border-bottom-style: none; border-left-color: oklch(0.551 0.027 264.364); border-left-style: none; border-right-color: oklch(0.551 0.027 264.364); border-right-style: none; border-top-color: oklch(0.551 0.027 264.364); border-top-left-radius: 8px; border-top-right-radius: 8px; border-top-style: none; box-shadow: none; color: oklch(0.556 0 0); color: oklch(0.708 0 0); display: flex; outline-color: oklab(0.556 0 0 / 0.5); outline-color: oklab(0.708 0 0 / 0.5); outline-offset: 0px; outline-width: 3px; padding-bottom: 12px; padding-left: 12px; padding-right: 12px; padding-top: 12px
vega: border-bottom-color: oklch(0.556 0 0); border-bottom-color: oklch(0.708 0 0); border-bottom-left-radius: 0px; border-bottom-right-radius: 0px; border-bottom-style: solid; border-left-color: oklch(0.556 0 0); border-left-color: oklch(0.708 0 0); border-left-style: solid; border-right-color: oklch(0.556 0 0); border-right-color: oklch(0.708 0 0); border-right-style: solid; border-top-color: oklch(0.556 0 0); border-top-color: oklch(0.708 0 0); border-top-left-radius: 0px; border-top-right-radius: 0px; border-top-style: solid; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgb(255, 255, 255) 0px 0px 0px 0px, oklab(0.556 0 0 / 0.5) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgb(255, 255, 255) 0px 0px 0px 0px, oklab(0.708 0 0 / 0.5) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; color: oklch(0.145 0 0); color: oklch(0.985 0 0); display: block; outline-color: rgba(0, 0, 0, 0); outline-offset: 2px; outline-width: 2px; padding-bottom: 4px; padding-left: 10px; padding-right: 6px; padding-top: 4px
ComboboxSearchInput — open/light, open/dark — RubyUI: full-width row with border-b, magnifier icon, input h-9 px-0. shadcn: InputGroup inside the content, *:data-[slot=input-group]:m-1 mb-0 h-8 bg-input/30 border-input/30 shadow-none rounded-md, no icon (style-vega.css:297). Requested: ComboboxInput as an InputGroup (no icon), role=combobox, aria-controls, aria-activedescendant.
↳ computed styles (shadcn-audit collect)
❌ Look column-gap: 4px; display: flex; gap: 4px; row-gap: 4px
vega: column-gap: normal; display: block; gap: normal; row-gap: normal
ComboboxList — open/light, open/dark — RubyUI: flex flex-col gap-1 p-1 max-h-72. shadcn cn-combobox-list: block, p-1 scroll-py-1 no-scrollbar max-h-[min(72-9 spacing, available-height)] (style-vega.css:325). Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
↳ computed styles (shadcn-audit collect)
⏸ Look ComboboxEmptyState: no visible element in any reached state. Reached by hand (typed 'zzz', both sides render it): RubyUI py-6 text-center text-sm, no muted color; shadcn cn-combobox-empty py-2 text-muted-foreground (style-vega.css:321). Requested: ComboboxEmpty with vega classes.
❌ Look border-bottom-width: 1px; column-gap: 4px; display: flex; gap: 4px; padding-bottom: 4px; padding-top: 4px; row-gap: 4px
vega: border-bottom-width: 0px; column-gap: normal; display: block; gap: normal; padding-bottom: 0px; padding-top: 0px; row-gap: normal
ComboboxListGroup — open/light, open/dark — RubyUI: flex flex-col py-1 gap-1 border-b, label drawn by ::before. shadcn cn-combobox-group has no classes; separation comes from ComboboxSeparator (bg-border -mx-1 my-1 h-px). Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
↳ computed styles (shadcn-audit collect)
❌ Look color: oklch(0.145 0 0); padding-bottom: 8px; padding-right: 8px; padding-top: 8px
vega: color: oklch(0.205 0 0); padding-bottom: 6px; padding-right: 32px; padding-top: 6px
ComboboxItem — open/light, open/dark — RubyUI: label p-2 gap-2 rounded-sm cursor-pointer, has-[:checked]:bg-accent. shadcn cn-combobox-item: py-1.5 pr-8 pl-2 gap-2 rounded-sm cursor-default, data-highlighted:bg-accent, check indicator absolute right-2 (style-vega.css:309, 317). Requested: check indicator on the right, aria-selected; native radio/checkbox kept sr-only for the form.
↳ computed styles (shadcn-audit collect)
⏸ Look properties: font-family, height, width
ComboboxTrigger, ComboboxPopover, ComboboxSearchInput, ComboboxList, ComboboxListGroup, ComboboxItem — explained by environment diff: font. font-family is the environment font diff (Inter Variable stack); height/width come from the fixture wrapper (div.w-64 vs Button w-64) and from item padding. Requested: render via Button(variant: :outline) + justify-between font-normal.
⚠️ ARIA aria-controls: (none); aria-haspopup: listbox; snapshot: only here: - button "Apple" [expanded]: | - text: Apple | - img; snapshot: only here: - button "Apple": | - text: Apple | - img
shadcn: aria-controls: resolves; aria-haspopup: dialog; snapshot: only here: - combobox [expanded]: Apple; snapshot: only here: - combobox: Apple
ComboboxTrigger — closed/light, open/light, focus/light, after-esc/light, closed/dark, open/dark, focus/dark, after-esc/dark Requested: render via Button(variant: :outline) + justify-between font-normal.
↳ accessibility tree (shadcn-audit collect)
⚠️ ARIA snapshot: only here: - img | - searchbox "Search" | - listbox: | - text: Fruits | - option "Apple": | - radio "Apple" [checked] | - text: Apple | - option "Banana": | - radio "Bana…
shadcn: snapshot: only here: - dialog: | - combobox "Search" [expanded] | - group | - listbox: | - group "Fruits": | - option "Apple" [selected] | - option "Banana" | - option "Blueberry…
ComboboxPopover — open/light, open/dark Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
↳ accessibility tree (shadcn-audit collect)
⚠️ ARIA aria-controls: (none); aria-expanded: (none); aria-haspopup: (none); snapshot: only here: - searchbox "Search"
shadcn: aria-controls: resolves; aria-expanded: true; aria-haspopup: listbox; snapshot: only here: - combobox "Search" [expanded]
ComboboxSearchInput — open/light, open/dark Requested: ComboboxInput as an InputGroup (no icon), role=combobox, aria-controls, aria-activedescendant.
↳ accessibility tree (shadcn-audit collect)
⚠️ ARIA snapshot: only here: - group: | - text: Fruits | - option "Apple": | - radio "Apple" [checked] | - text: Apple | - option "Banana": | - radio "Banana" | - text: Banana | …
shadcn: snapshot: only here: - group "Fruits": | - option "Apple" [selected] | - option "Banana" | - option "Blueberry" | - option "Grapes" | - option "Pineapple"
ComboboxList — open/light, open/dark Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
↳ accessibility tree (shadcn-audit collect)
⏸ ARIA ComboboxEmptyState: no visible element in any reached state. Reached by hand: both render the empty text; shadcn's is inside the dialog, outside the listbox. Requested: ComboboxEmpty with vega classes.
⚠️ ARIA snapshot: only here: - group: | - text: Fruits | - option "Apple": | - radio "Apple" [checked] | - text: Apple | - option "Banana": | - radio "Banana" | - text: Banana | - option "Bluebe…
shadcn: snapshot: only here: - group "Fruits": | - option "Apple" [selected] | - option "Banana" | - option "Blueberry" | - option "Grapes" | - option "Pineapple"
ComboboxListGroup — open/light, open/dark Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
↳ accessibility tree (shadcn-audit collect)
⚠️ ARIA snapshot: only here: - option "Apple": | - radio "Apple" [checked] | - text: Apple; snapshot: only here: - option "Banana": | - radio "Banana" | - text: Banana; snapshot: only here: - option "Blueberry": | - radio "Blueberry" | - text: Blueberry; snapshot: only here: - option "Grapes": | - radio "Grapes" | - text: Grapes; snapshot: only here: - option "Pineapple": | - radio "Pineapple" | - text: Pineapple
shadcn: snapshot: only here: - option "Apple" [selected]; snapshot: only here: - option "Banana"; snapshot: only here: - option "Blueberry"; snapshot: only here: - option "Grapes"; snapshot: only here: - option "Pineapple"
ComboboxItem — open/light, open/dark Requested: check indicator on the right, aria-selected; native radio/checkbox kept sr-only for the form.
↳ accessibility tree (shadcn-audit collect)
❌ HTML Combobox: div[role=combobox] wrapping trigger + popover
shadcn: Combobox root renders no element; the trigger button carries role=combobox
RubyUI puts the combobox role on a wrapper, not on the control that opens the list. Requested: root without role; role=combobox on the trigger/input; popup role=dialog.
↳ bases/base/ui/combobox.tsx:16
❌ HTML ComboboxPopover: div[popover][role=popover], inline next to the trigger
shadcn: Portal > Positioner > Popup[role=dialog][data-slot=combobox-content]
Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
↳ bases/base/ui/combobox.tsx:101
❌ HTML ComboboxSearchInput: div.border-b > svg(search) + input[type=search][role=searchbox]
shadcn: InputGroup > input[role=combobox][data-slot=input-group-control] (ComboboxInput showTrigger={false})
Requested: ComboboxInput as an InputGroup (no icon), role=combobox, aria-controls, aria-activedescendant.
↳ bases/base/ui/combobox.tsx:66
❌ HTML ComboboxItem: label[role=option] > input[type=radio] (visible) + span
shadcn: div[role=option][data-slot=combobox-item] > text + span.cn-combobox-item-indicator (check icon, right)
RubyUI shows a radio/checkbox on the left; shadcn shows a check on the right only on the selected item. Requested: check indicator on the right, aria-selected; native radio/checkbox kept sr-only for the form.
↳ bases/base/ui/combobox.tsx:151
❌ HTML ComboboxListGroup(label:) draws the label with ::before content: attr(label)
shadcn: ComboboxGroup > ComboboxLabel (div[data-slot=combobox-label], text-muted-foreground px-2 py-1.5 text-xs)
Pseudo-element text isn't a group name: the ARIA snapshot shows an unnamed group on RubyUI. Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
↳ bases/base/ui/combobox.tsx:192
❌ HTML no part
shadcn: ComboboxSeparator, ComboboxValue, ComboboxCollection, ComboboxInput (input as trigger), ComboboxChips/Chip/ChipsInput
Missing parts. ComboboxInputTrigger / ComboboxBadgeTrigger / ComboboxBadge / ComboboxClearButton exist but are not wired (see Behavior). Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
↳ bases/base/ui/combobox.tsx:221
❌ Props Combobox(placement: 'bottom-start'), offset fixed at 4px
shadcn: ComboboxContent side='bottom' sideOffset=6 align='start' alignOffset=0 anchor
placement covers side+align on the root; no sideOffset/alignOffset/anchor. Requested: side/side_offset/align/align_offset on ComboboxContent.
↳ bases/base/ui/combobox.tsx:101
❌ Props ComboboxInputTrigger(placeholder:), no disabled/show_trigger/show_clear
shadcn: ComboboxInput showTrigger showClear disabled
Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
↳ bases/base/ui/combobox.tsx:66
❌ Props ComboboxBadge: no remove control
shadcn: ComboboxChip showRemove (ChipRemove button)
Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
↳ bases/base/ui/combobox.tsx:248
⚠️ Behavior open: focus stays on the trigger button; ArrowDown/typing/Enter do nothing until the user clicks the search input
shadcn: open: focus moves to the search input[role=combobox]; ArrowDown/typing/Enter work at once
Browser run, 1280x800. ComboboxPopover has autofocus on a div, which doesn't move focus to the input. Requested: match shadcn (focus into input, aria-activedescendant, selected highlighted on open, focus back to trigger).
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
⚠️ Behavior open: no option active; active option = aria-current + ring on the label
shadcn: open: selected item (Apple) highlighted; active option = data-highlighted + input aria-activedescendant
Requested: match shadcn (focus into input, aria-activedescendant, selected highlighted on open, focus back to trigger).
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#roles_states_properties
⚠️ Behavior outside click closes; focus drops to body
shadcn: outside click closes; focus returns to the trigger
Requested: match shadcn (focus into input, aria-activedescendant, selected highlighted on open, focus back to trigger).
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
✅ Behavior typing filters (b → Banana, Blueberry), 'zzz' shows the empty state, ArrowDown+Enter selects Blueberry and closes, Esc closes and returns focus to the trigger
Once focus is in the search input.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
⏸ Behavior ComboboxInputTrigger, ComboboxBadgeTrigger, ComboboxClearButton
shadcn: ComboboxInput, ComboboxChips, ComboboxClear
Not in the fixture. Static read: they wire targets/actions the controller doesn't declare (inputTrigger, badgeInput, badgeContainer, clearButton, clearAll, handleBadgeInputBackspace) and filterItems reads only searchInputTarget, so they can't work as shipped. Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
⚠️ Animation none (animation-name: none)
shadcn: fade-in-0 zoom-in-95 slide-in-from-top-2, 100ms (data-open/data-closed)
Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
↳ style-vega.css:297
✅ Native popover attribute: top layer, light dismiss, Esc, focus back to the trigger — native
Positioning still uses Floating UI (native-html.md: popover doesn't position; anchor positioning is a separate follow-up).
↳ https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover
✅ Native radio/checkbox inputs carry the form value — native
↳ https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/radio
❌ Spec Combobox wrapper div[role=combobox] has no aria-expanded
shadcn: trigger button[role=combobox][aria-expanded]
aria-expanded is a required state of combobox in ARIA 1.2; RubyUI only sets it on the inner button. Requested: root without role; role=combobox on the trigger/input; popup role=dialog.
↳ https://www.w3.org/TR/wai-aria-1.2/#combobox
❌ Spec ComboboxPopover role="popover"
shadcn: Popup role=dialog
"popover" is not a WAI-ARIA role, so the role is ignored. Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
↳ https://www.w3.org/TR/html-aria/#docconformance
✅ Spec —
shadcn side conforms to the APG combobox pattern.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#roles_states_properties
⏸ Props ComboboxToggleAllCheckbox, Combobox(term:)
shadcn: no counterpart
RubyUI-only extras. Suggested divergence: keep Select all and term:, register in audit/divergences/combobox.yml.
shadcn audit on this branch (after)
shadcn audit ruby-ui/ruby_ui
base 7e65e61f head 02758cd3 shadcn 4aaea19d
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme neutral tokens match shadcn
Combobox (ref: bases/base/ui/combobox.tsx + style-vega.css @ 4aaea19d)
⏸ Look ComboboxEmpty: no visible element in any reached state. Reached by hand (typed 'zzz'): see the ComboboxEmpty Look/ARIA lines below.
⏸ Look properties: font-family, height
ComboboxTrigger, ComboboxInput, ComboboxContent, ComboboxList, ComboboxGroup, ComboboxLabel, ComboboxItem — explained by environment diff: font. font-family is the environment font diff; height follows from it and from the fixture wrapper.
⏸ ARIA ComboboxEmpty: no visible element in any reached state. Reached by hand (typed 'zzz'): see the ComboboxEmpty Look/ARIA lines below.
✅ ARIA ComboboxTrigger, ComboboxInput, ComboboxContent, ComboboxList, ComboboxGroup, ComboboxLabel, ComboboxItem: accessibility tree matches
↳ accessibility tree (shadcn-audit collect)
✅ Look ComboboxEmpty (typed 'zzz'): flex, py-2 (8px 0), 14px, oklch(0.556 0 0), 284x36
Computed styles compared by hand; collect doesn't type into the input.
↳ style-vega.css:321
✅ ARIA ComboboxEmpty: role=status aria-live=polite aria-atomic=true
Read from the DOM on both sides.
↳ bases/base/ui/combobox.tsx:211
✅ HTML Combobox root: div without role; trigger button[role=combobox]; popup [popover] role=dialog > input group (role=group) + empty + listbox > group > options
The wrapper div holds the Stimulus controller and has no role.
↳ bases/base/ui/combobox.tsx:101
✅ HTML ComboboxItem: div[role=option][aria-selected] + check span (aria-hidden) on the right; ComboboxLabel div[aria-hidden] named through aria-labelledby; ComboboxSeparator div[role=separator]
↳ bases/base/ui/combobox.tsx:151
✅ HTML Visually hidden native radio/checkbox inside each item — intentional
Server-rendered component: the checked inputs are the selection, so the form submits it and required:/FormField validation work natively.
↳ audit/divergences/combobox.yml
✅ HTML ComboboxInput (input as trigger, show_trigger/show_clear), ComboboxChips/Chip/ChipsInput
Not in the fixture; exercised on /docs/combobox: open from the input and from the chevron, filter, Enter, clear by click and by Tab+Enter, chips, Backspace, chip remove.
↳ bases/base/ui/combobox.tsx:66
✅ Props ComboboxContent(side:, side_offset:, align:, align_offset:); ComboboxInput(show_trigger:, show_clear:, disabled:)
Side top checked on the docs page (opens above, flips when there is no room).
↳ bases/base/ui/combobox.tsx:101
✅ Props show_remove: on ComboboxChips; no anchor: (chips anchor automatically) — intentional
The controller builds chips from a template, so the option lives on the container.
↳ audit/divergences/combobox.yml
✅ Props ComboboxToggleAll, Combobox(term:) — intentional
RubyUI extras kept from the previous API; Select all checked with chips and in a popup.
↳ audit/divergences/combobox.yml
✅ Props ComboboxChips(max:): past the cap, one "<count> <term>" chip that clears the selection — intentional
RubyUI extra for large selections.
↳ audit/divergences/combobox.yml
✅ Behavior open: focus to the search input, selected item highlighted, aria-activedescendant; ArrowDown, Home, End move; Enter selects and closes; focus back to the trigger
Browser run, 1280x800, step by step on both sides.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
✅ Behavior typing filters (ban → Banana), 'zzz' shows the empty state; Esc closes and returns focus; outside click closes and focus returns to the trigger
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
✅ Behavior input as trigger and multiple: chips, Backspace and × remove (disabled items stay), Select all, max: summary chip; required: (single and multiple) validated by the browser, FormField's aria-invalid/aria-describedby on the visible control
Docs page run, no console errors.
↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
✅ Animation open: enter 0.1s (fade-in-0 zoom-in-95 slide-in-from-top-2); close: exit 0.1s, then hidePopover
↳ style-vega.css:297
⚠️ Native popover="manual": top layer from the platform, Esc and outside click handled by the controller
shadcn: Base UI JS popup
popover="auto" would light-dismiss when the user clicks the input that triggers it (it sits outside the popup), and closes without the exit animation. Native radio/checkbox still carry the form value.
↳ https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover
✅ Spec trigger/input role=combobox with aria-expanded, aria-controls (trigger: only while open), aria-haspopup; no invalid roles
The role="popover" and the role=combobox wrapper without aria-expanded from main are gone.
↳ https://www.w3.org/TR/wai-aria-1.2/#combobox
🤖 Generated with Claude Code
Summary by cubic
Rewrites Combobox to match shadcn's Base UI combobox with vega styling. Breaking change: part names and the root API change, with no aliases for the old API. This fixes the audit findings on main: focus stayed on the trigger after opening so arrow keys did nothing, an invalid role="popover", a role=combobox wrapper with no aria-expanded, and ComboboxInputTrigger, ComboboxBadgeTrigger, ComboboxBadge and ComboboxClearButton shipped pointing at controller code that doesn't exist.
Migration
| Before | After |
|---|---|
Combobox(term:, placement:) | Combobox(name:, multiple:, term:, disabled:, required:); placement moves to ComboboxContent(side:, align:, side_offset:, align_offset:) |
ComboboxTrigger(placeholder: "...") | ComboboxTrigger { ComboboxValue(placeholder: "...") } |
ComboboxPopover | ComboboxContent |
ComboboxSearchInput(placeholder:) | ComboboxInput(placeholder:, show_trigger: false) inside ComboboxContent |
ComboboxEmptyState | ComboboxEmpty |
ComboboxListGroup(label: "Fruits") | ComboboxGroup { ComboboxLabel { "Fruits" } ... }, plus ComboboxSeparator |
ComboboxItem { ComboboxRadio(name:, value:); span { "Apple" } } | ComboboxItem(value: "apple") { "Apple" } (name comes from the root) |
ComboboxCheckbox | Combobox(multiple: true) makes every item a checkbox |
CheckboxGroup(required: true) around the items | Combobox(multiple: true, required: true) |
ComboboxToggleAllCheckbox | ComboboxToggleAll { "Select all" } |
ComboboxInputTrigger | ComboboxInput(placeholder:, show_clear:) outside the content |
ComboboxBadgeTrigger, ComboboxBadge, ComboboxClearButton | ComboboxChips(max:) { ComboboxChipsInput } |
Behavior changes
- The controller follows the APG combobox pattern like Base UI: focus stays in the input, the active option goes through
aria-activedescendant, the selected item is highlighted on open, Home and End jump to the ends, and Escape and outside clicks return focus to the trigger; the popup fades and zooms over 100 ms. - The popup is a
popover="manual"top-layer element positioned by Floating UI;popover="auto"would close it when clicking the input that opens it. - Each item keeps a visually hidden native radio/checkbox so forms submit the selection, and
FormField'saria-invalidandaria-describedbymove onto the visible input or trigger;required:without aname:now raises an ArgumentError, and Form reset refreshes chips, value and required flags since the reset unchecks inputs without firing change. - Chip remove buttons label the item they remove and sit in the tab order; clicking the input group addon focuses the input. A group gets
aria-labelledbyonly when aComboboxLabelrenders, andaria-controlsfollows a customComboboxListid. ComboboxToggleAll,term:andComboboxChips(max:)have no shadcn counterpart and are registered inaudit/divergences/combobox.yml.- Combobox now depends on Button (
dependencies.yml); the Form docs example, fixtures and MCP registry are updated.