Dropdown

Use one API per dropdown. Switch the API control (top right) to read docs for that API only. If options is set, any <catnip-dropdown-option> children are ignored.

---

Supplying options — options prop

Pass an array of plain objects. Bind reactively with .options (Vue property binding).

<script setup>
import { ref } from "vue";

const services = ref([
  { value: "audit", label: "Audit API" },
  { value: "auth", label: "Auth solution", disabled: true },
  { value: "sign", label: "Electronic Signature" }
]);
const selected = ref("audit");
</script>

<template>
  <catnip-dropdown
    label="Service"
    placeholder="Select a service"
    .options="services"
    .modelValue="selected"
    @update:modelValue="selected = $event.detail[0]"
  />
</template>

Option object shape

Field	Type	Required	Description
value	string | number | boolean	yes	Stored in modelValue (same scalar types).
label	string	no	Display and typeahead text; defaults to value.
disabled	boolean	no	Non-interactive row.
hidden	boolean	no	Omitted from the panel (client-side filter).
intent	"default" | "danger"	no	Row intent; default default.

Filterable with options

Built-in label filter is on by default (filterLocally defaults to true):

<catnip-dropdown label="Service" filterable .options="services" .modelValue="selected" @update:modelValue="selected = $event.detail[0]" />

Pre-filter in the parent (e.g. server search) — pass a computed array and disable local filtering:

<catnip-dropdown
  filterable
  .filterLocally="false"
  .options="filteredServices"
  .filterValue="query"
  @update:filterValue="query = $event.detail[0]"
  …
/>

---

catnip-dropdown

Props

Value & selection

Prop	Type	Default	Description
options	CatnipDropdownOptionData[]	—	Plain option rows. When set, child <catnip-dropdown-option> elements are ignored.
modelValue	CatnipDropdownModelValue	—	Selected value(s). Array when multiple. Empty single: "", null, or undefined.
multiple	boolean	false	Checkbox rows; modelValue is an array of scalars.
selectAll	boolean	false	Multi only. Shows a Select all row above options; toggles visible enabled rows.
displayMode	string	"value"	Multi only: value, chips, count.
placeholder	string	""	Trigger text when empty.
name	string	""	Form submission name.
required	boolean	false	Label marker + native required semantics.

Field presentation

Prop	Type	Default	Description
label	string	""	Visible field label when the label slot is empty.
optional	boolean	false	When true and not required, shows the localized optional hint.
optionalText	string	""	Overrides the localized optional hint (HTML: optional-text).
info	string	""	Info tooltip beside the label; when non-empty, it wins over the label.suffix slot.
alignment	"left" | "center" | "right"	"left"	Horizontal alignment of the field label block.
requiredMarker	string	"*"	Visual marker for required fields (HTML: required-marker).
requiredScreenReaderText	string	""	Optional screen-reader supplement; it does not replace required on the control (HTML: required-screen-reader-text).
size	"s" | "m" | "l"	"m"	s, m, l — trigger and field density.
intent	"neutral" | "danger" | "warning" | "success"	"neutral"	Semantic state applied to field and supporting-text styling; danger sets aria-invalid on the trigger.
disabled	boolean	false	Disables the field.
readonly	boolean	false	Prevents opening the panel.
hideLabel	boolean	false	Hides the built-in label row.
supportingText	SupportingTextProp	""	One or more helper or validation messages. Each object requires text; intent accepts neutral, danger, warning, or success, and icon accepts a Catnip icon name. See supporting-text examples.

Panel & filter

Prop	Type	Default	Description
open	boolean | null	null	Controlled open state. null = uncontrolled. Pair with open-change.
listMaxHeight	string | number	280px	Scrollable list body max height.
listMaxWidth	string | number	320px	Open list max width. Empty string removes the cap. Never narrower than the trigger.
filterable	boolean	false	Built-in search row in list header (label filter).
filterLocally	boolean	true	When false, skip built-in label filtering (parent owns visible rows).
filterPlaceholder	string	""	Placeholder for built-in search.
filterValue	string	""	Controlled filter text.
catnipInput	CatnipInputControlProps	{}	Props forwarded to built-in filter catnip-input.
showClearButton	boolean	false	Clears selection (single → "", multi → []).
clearButtonAriaLabel	string	""	Clear button label; defaults to bundled dropdown.clear.
selectAllLabel	string	""	Select-all row label; defaults to bundled dropdown.selectAll.
selectedCountLabel	string	""	Count mode template; {count} placeholder.
maxVisibleChips	number	—	Chips mode overflow before “show more”.

Advanced

Prop	Type	Default	Description
ariaLabel	string	""	Trigger aria-label when no visible label.
ariaDescribedby	string	""	Extra id values merged into aria-describedby alongside generated supporting-text ids.
testSelectors	TestSelectorsProp	See below	Overrides stable data-test values.

Derived behaviour: single-select uses checkmark rows; multi-select uses checkbox rows. Chevron flips when open.

Slots

Slot	Description
label, label.action, label.suffix	Field label row
trigger	Full trigger override — see Trigger slot below
value	Selected value area inside default trigger
leftIconSlot, rightIconSlot	Trigger adornments
listHeader	Panel header — wins over filterable
listFooter	Panel footer (e.g. Add new)
catnipInput.leftIconSlot, catnipInput.rightIconSlot	Forwarded to built-in filter input

Trigger slot

When trigger is set, the default combobox shell is replaced. The slot is wrapped in an anchor element used to position the floating panel.

• Include a focusable control (e.g. <button type="button">) with appropriate role="combobox", aria-expanded, aria-controls, and aria-activedescendant (or equivalent labelling).
• Open/close and keyboard behaviour are still driven by the dropdown; wire @click / @keydown on your control if you replace the default trigger entirely.
• A dev warning is logged if no focusable element is found inside the slot.

Events

Event	Payload	Description
update:modelValue	scalar or array	Selection changed (string, number, or boolean).
open-change	boolean	Open state changed (true / false). Use @open-change.
update:filterValue	string	Filter text (filterable).
close	—	Panel dismissed.

Test selectors

Key	Default
root	catnip-dropdown
trigger	catnip-dropdown-trigger
value	catnip-dropdown-value
chevron	catnip-dropdown-chevron
clearButton	catnip-dropdown-clear
supportingText	catnip-dropdown-supporting-text

Nested: floatingPanel, list, filterInput (same keys as embedded components).

---

---

Examples

Multi-select with chips

<catnip-dropdown
  label="Services"
  multiple
  display-mode="chips"
  .options="services"
  .modelValue="selected"
  @update:modelValue="selected = $event.detail[0]"
/>

Multi-select with select all

<catnip-dropdown
  label="Hobbies"
  multiple
  select-all
  display-mode="chips"
  filterable
  .options="hobbies"
  .modelValue="selected"
  @update:modelValue="selected = $event.detail[0]"
/>

When filterable is on, Select all applies to the visible filtered rows only. Selections outside the current filter stay unchanged.