KikitaUiDocs

On this page - Import

import { KuiDropdown, KuiDropdownFor, KuiOption } from '@kikita-labs/ui';

// Import runtime styles once, application-wide:
import '@kikita-labs/ui/styles';

<div class="standalone-dropdown-example">
  <button kuiButton type="button" [kuiDropdownFor]="menu">Actions</button>

  <kui-dropdown #menu [maxHeight]="null">
    <div kuiOption value="edit">Edit</div>
    <div kuiOption value="delete" [disabled]="true">Delete</div>
  </kui-dropdown>
</div>

<div class="controlled-open-dropdown-example">
  <div class="controlled-open-dropdown-example__actions">
    <button kuiButton type="button" [kuiDropdownFor]="results">Show results</button>
    <button kuiButton type="button" shape="soft" (click)="resultsOpen.set(true)">
      Open from parent
    </button>
  </div>

  <kui-dropdown #results [(open)]="resultsOpen" panelWidth="anchor" [panelRole]="null">
    <div kuiOption value="alpha">Alpha result</div>
    <div kuiOption value="beta">Beta result</div>
  </kui-dropdown>
</div>

Fruit

<kui-field label="Fruit">
  <input kuiSelect [(value)]="fruit" placeholder="Pick..." />
  <kui-dropdown>
    <div kuiOption value="apple">Apple</div>
    <div kuiOption value="banana">Banana</div>
    <div kuiOption value="cherry">Cherry</div>
  </kui-dropdown>
</kui-field>

<div class="panel-width-dropdown-example">
  <button kuiButton type="button" [kuiDropdownFor]="anchorPanel">panelWidth="anchor"</button>
  <kui-dropdown #anchorPanel panelWidth="anchor">
    <div kuiOption value="a">Matches trigger width</div>
  </kui-dropdown>

  <button kuiButton type="button" [kuiDropdownFor]="contentPanel">panelWidth="content"</button>
  <kui-dropdown #contentPanel panelWidth="content">
    <div kuiOption value="b">Grows with a longer content line if needed</div>
  </kui-dropdown>

  <button kuiButton type="button" [kuiDropdownFor]="explicitPanel">width="320px"</button>
  <kui-dropdown #explicitPanel width="320px">
    <div kuiOption value="c">Always exactly 320px wide</div>
  </kui-dropdown>
</div>

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        dropdown: {
          /* options below */
        },
      },
    }),
  ],
};

Name	Type	Default	Description
maxHeight	`string \| null`	—	Maximum panel height as a CSS length, or null for no limit.
offset	`number`	—	Gap in px between the anchor and the panel edge.
closeOnSelect	`boolean`	—	Closes the panel when a selectable option is clicked.
panelWidth	`'anchor' \| 'content' \| 'auto'`	—	Panel width relative to the anchor.

Name	Type	Default	Description
--kui-dropdown-font-size	`CSS custom property`	`--kui-text-sm-size`	Font size
--kui-dropdown-padding	`CSS custom property`	`--kui-space-1`	Padding
--kui-dropdown-max-height	`CSS custom property`	`240px`	Panel max height (the maxHeight input and defaults.dropdown.maxHeight win)

Name	Type	Default	Description
maxHeight	`string \| null \| undefined`	`'240px' (--kui-dropdown-max-height)`	Preferred max height of the panel before it scrolls. Falls back to defaults.dropdown.maxHeight, then the --kui-dropdown-max-height token (240px). Always additionally clamped to the viewport so the panel can never render taller than the screen. null removes only the preferred cap, not the viewport clamp.
offset	`number \| undefined`	`4`	Gap in px between the anchor and the panel edge. A static numeric attribute is coerced. Falls back to defaults.dropdown.offset.
closeOnSelect	`boolean \| undefined`	`true`	Closes the panel after an enabled option is selected with a pointer or Enter/Space. A plain input (it is no longer a two-way model). Falls back to defaults.dropdown.closeOnSelect.
open	`ModelSignal<boolean>`	`false`	Controlled open state. Bind with [(open)] to keep parent state synchronized with Escape, outside-click, and off-screen-anchor dismissal. Imperative open(), close(), and toggle() remain available.
panelRole	`'listbox' \| 'dialog' \| 'grid' \| null`	`'listbox'`	ARIA role rendered on the panel. Set to dialog (or null to omit the role) for non-listbox projected content, e.g. kui-calendar.
panelWidth	`'anchor' \| 'content' \| 'auto' \| undefined`	`'anchor'`	Falls back to defaults.dropdown.panelWidth. anchor matches the trigger's width exactly (listboxes). content grows with the panel's own content but never below the trigger's width. auto ignores the trigger's width and sizes purely to content.
width	`string \| null`	`null`	Explicit panel width (any CSS width, e.g. 320px). Overrides panelWidth entirely when set.
isOpen	`Signal<boolean>`	`-`	Current open state.
open()	`method`	`-`	Shows the panel and attaches scroll/outside-click/Escape listeners.
close()	`method`	`-`	Starts the close animation and detaches listeners.
toggle()	`method`	`-`	Opens when closed, closes when open.
setAnchor(el, focusReturn?)	`method`	`-`	Sets the anchor imperatively. The optional third argument names the element that receives focus when the panel closes after a selection or Escape. Called by kui-field and [kuiDropdownFor].
getPanel()	`method`	`-`	Returns the rendered panel element, if attached.
getPanelId()	`method`	`-`	Returns the stable panel id for ARIA wiring.
[kuiDropdownFor]	`KuiDropdown`	`-`	Wires a standalone trigger to a dropdown instance and manages click toggling, aria-expanded, and aria-haspopup. Prefer a native button so keyboard behavior is already correct.
[kuiOption] value	`unknown`	`-`	Required. The value an option renders and emits. Set via the `value` input on `KuiOption`, e.g. `<div kuiOption value="edit">`.
[kuiOption] disabled	`boolean`	`false`	Disables click and keyboard selection for this option.
kuiOptionSelect	`EventEmitter<unknown>`	`-`	Emits the option value on selection.
--kui-dropdown-bg	`CSS custom property`	`var(--kui-color-surface-elevated)`	Panel background.
--kui-dropdown-border	`CSS custom property`	`var(--kui-color-border)`	Panel border color.
--kui-dropdown-radius	`CSS custom property`	`var(--kui-radius-md)`	Panel corner radius.
--kui-dropdown-shadow	`CSS custom property`	`var(--kui-shadow-lg)`	Panel drop shadow.
--kui-dropdown-viewport-margin	`CSS custom property`	`var(--kui-space-6, 32px)`	Margin subtracted from the viewport height when clamping the panel max-height.
Known non-feature	`-`	`-`	Dropdown does not own selection or value state itself. Select, Combobox, Menu, or another host component provides that context; a bare kui-dropdown only positions the panel and manages open/close.
KuiDropdownOptions	`interface`	`-`	Shape of defaults.dropdown: maxHeight, offset, closeOnSelect and panelWidth.

Provider defaults

Theming tokens