@rozie-ui/combobox-vue

@rozie-ui/combobox-vue

Idiomatic vue Combobox — a headless, fully-accessible (WAI-ARIA) combobox / autocomplete: a text input plus a popup listbox with aria-activedescendant keyboard navigation (Arrow/Home/End/Enter/Escape), built-in client-side filtering (or async/server-side via the search event + disableFilter), a custom-option scoped slot, and a two-way value binding — compiled from one Rozie source. There is NO third-party engine; the behaviour is authored once on native DOM. Every visual value is a CSS custom property, so it re-skins to any design system. This package is generated; do not edit src/ by hand.

Install

npm i @rozie-ui/combobox-vue

Peer dependencies: vue. Install them alongside this package.

Required peers — beyond the framework peer above, this package requires these non-optional peers to actually render:

• @rozie-ui/popover-vue ^0.2.0 || ^0.3.0 — required by @rozie-ui/combobox-vue
• @tanstack/virtual-core ^3 — required by @rozie-ui/combobox-vue
• @floating-ui/dom ^1.7.2 — required by @rozie-ui/popover-vue

Install the whole chain in one line:

npm i @rozie-ui/combobox-vue @rozie-ui/popover-vue @tanstack/virtual-core @floating-ui/dom

Also installed: @rozie/runtime-vue — Rozie's small, tree-shaken runtime helper package (controllable state, keyboard navigation, event modifiers, and safe interpolation). It arrives as a regular dependency, so npm pulls it for you. This build imports nothing from it today, so it shakes out of your bundle entirely. What's in it and what it costs.

Usage

<script setup lang="ts">
import { ref } from 'vue';
import Combobox from '@rozie-ui/combobox-vue';

const value = ref<string | null>(null);
const frameworks = [
  { value: 'react', label: 'React' },
  { value: 'vue', label: 'Vue' },
  { value: 'svelte', label: 'Svelte' },
  { value: 'solid', label: 'Solid' },
];
function onChange(e: { value: unknown }) {
  console.log('picked:', e.value);
}
</script>

<template>
  <Combobox v-model:value="value" :options="frameworks" placeholder="Search…" aria-label="Framework" @change="onChange" />

  <!-- Custom option rendering via the #option scoped slot -->
  <Combobox v-model:value="value" :options="frameworks">
    <template #option="{ option, selected }">
      <strong v-if="selected">{{ option.label }}</strong>
      <span v-else>{{ option.label }}</span>
    </template>
  </Combobox>
</template>

Theming

Every visual value is a --rozie-combobox-* CSS custom property — override any of them at any ancestor scope. Ready-made design-system bridges ship in the package:

import '@rozie-ui/combobox-vue/themes/shadcn.css';    // or material.css, bootstrap.css, base.css

Props

Events

Imperative handle

Beyond props, the component exposes imperative methods (declared once in the Rozie source via $expose). Grab a handle with the native ref mechanism and call them directly. Note: focus() deliberately overrides the inherited HTMLElement.focus (it focuses the text input) — on the Lit custom element this is an accepted ROZ137 warn-only override, the public focus() handle is intended:

<script setup>
import { ref } from 'vue';
const cb = ref();          // template ref
</script>

<template>
  <Combobox ref="cb" v-model:value="value" :options="frameworks" />
  <button @click="cb.clear()">Clear</button>
</template>

Slots