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	string | number | boolean | array of those	—	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

Same label row props as Input (label, info, optional, alignment, …) and supportingText.

Prop	Type	Default	Description
size	string	"m"	s, m, l — trigger and field density.
intent	string	"neutral"	neutral, warning, danger, success.
disabled	boolean	false	Disables the field.
readonly	boolean	false	Prevents opening the panel.
hideLabel	boolean	false	Hides the built-in label row.

Panel & filter

Prop	Type	Default	Description
open	boolean	—	Controlled open state (optional).
listMaxHeight	string | number	280px	Scrollable list body max height.
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	object	{}	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 describedby ids (supporting text id added automatically).
testSelectors	object	See below	data-test overrides.

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
list-header	Panel header — wins over filterable
list-footer	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).
update:open	boolean	Open state (controlled open).
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.