# Combobox

> Memilih satu nilai dari daftar panjang dengan mengetik untuk mencarinya.

Combobox adalah kolom teks dengan daftar: orang mengetik untuk menyaring daftar, lalu memilih satu nilai dengan mouse atau keyboard.

## Kapan dipakai

- Pakai untuk lebih dari 15 pilihan, atau saat orang tahu apa yang dicarinya, misalnya artis, lagu, atau perusahaan.
- Pakai [Select](https://design.sosialoka.tech/id/components/select/) untuk 4 sampai 15 pilihan, dan [Radio Group](https://design.sosialoka.tech/id/components/radio-group/) untuk 2 atau 3.
- Tulis teks kosong untuk daftarnya, misalnya "Artis tidak ditemukan.", supaya orang tahu pencariannya sudah jalan.

**Mencari di server.** Kalau daftarnya ada di backend, cari sambil orang mengetik: tunggu sekitar 300ms setelah ketikan terakhir, biarkan hasil sebelumnya tampil selama hasil berikutnya dimuat, dan tampilkan [Spinner](https://design.sosialoka.tech/id/components/spinner/) di daftar. Backend yang menentukan apa yang cocok.

_Pratinjau langsung versi React dan Vue: https://design.sosialoka.tech/id/components/combobox/_

## Anatomi

1. Input untuk mengetik
2. Teks yang diketik dan kursor
3. Pilihan yang cocok
4. Daftar

1. **Input**: kolom teks dengan `radius-md` dan border `input`, tinggi `h-9`.
2. **Daftar**: popup berlatar `popover` dengan `border`, `radius-lg`, dan `shadow-lg`, selebar input.
3. **Item**: `radius-md`; item yang disorot berlatar `accent` dan yang terpilih bertanda centang.
4. **Teks kosong**: tampil saat tidak ada yang cocok.

## Varian

Hanya ada satu gaya. React juga punya chip (`ComboboxChips`) untuk memilih beberapa nilai.

## Props

| React | Vue | Flutter | Tipe | Default | Kegunaan |
| --- | --- | --- | --- | --- | --- |
| `items` di `Combobox` | children `ComboboxItem` | `options` di `ShadSelect.withSearch` | list | tidak ada | Daftar pilihan. |
| `value` / `defaultValue` | `v-model` | `initialValue` | nilai | tidak ada | Nilai terpilih. |
| `onValueChange` | `@update:model-value` | `onChanged` | function | tidak ada | Jalan saat nilai dipilih. |
| `placeholder` di `ComboboxInput` | `placeholder` di `ComboboxInput` | `placeholder` | teks | tidak ada | Tampil sebelum ada pilihan. |
| `ComboboxEmpty` | `ComboboxEmpty` | baris kosong di `options` | teks | tidak ada | Memberi tahu bahwa tidak ada yang cocok. |
| `onInputValueChange` | `@update:model-value` di `ComboboxInput` | `onSearchChanged` | function | tidak ada | Jalan saat orang mengetik, untuk pencarian di server. |

## Kode

**React**
```tsx
import { useId } from "react"
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
import { Field, FieldLabel } from "@/components/ui/field"

const artists = ["Rara Senandika", "Bima Laras", "Nada Kirana", "Arka Wening", "Sinta Maharani", "Raka Pratama"]

export default function ComboboxDemo() {
  const id = useId()
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel htmlFor={`${id}-artist`}>Artis</FieldLabel>
      <Combobox items={artists}>
        <ComboboxInput id={`${id}-artist`} placeholder="Pilih artis" />
        <ComboboxContent>
          <ComboboxEmpty>Artis tidak ditemukan.</ComboboxEmpty>
          <ComboboxList>
            {(artist: string) => (
              <ComboboxItem key={artist} value={artist}>
                {artist}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </Field>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { ref, useId } from "vue"
import { CheckIcon } from "@lucide/vue"
import {
  Combobox,
  ComboboxAnchor,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxItemIndicator,
  ComboboxList,
} from "@/components/ui/combobox"
import { Field, FieldLabel } from "@/components/ui/field"

const artists = ["Rara Senandika", "Bima Laras", "Nada Kirana", "Arka Wening", "Sinta Maharani", "Raka Pratama"]
const id = useId()
const artist = ref<string>()
</script>

<template>
  <Field class="w-full max-w-xs">
    <FieldLabel :for="`${id}-artist`">Artis</FieldLabel>
    <Combobox v-model="artist">
      <ComboboxAnchor>
        <ComboboxInput :id="`${id}-artist`" placeholder="Pilih artis" :display-value="(value: string) => value ?? ''" />
      </ComboboxAnchor>
      <ComboboxList>
        <ComboboxEmpty>Artis tidak ditemukan.</ComboboxEmpty>
        <ComboboxItem v-for="name in artists" :key="name" :value="name">
          {{ name }}
          <ComboboxItemIndicator>
            <CheckIcon />
          </ComboboxItemIndicator>
        </ComboboxItem>
      </ComboboxList>
    </Combobox>
  </Field>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

const artists = ['Rara Senandika', 'Bima Laras', 'Nada Kirana', 'Arka Wening', 'Sinta Maharani', 'Raka Pratama'];

class ComboboxDemo extends StatefulWidget {
  const ComboboxDemo({super.key});

  @override
  State<ComboboxDemo> createState() => _ComboboxDemoState();
}

class _ComboboxDemoState extends State<ComboboxDemo> {
  String search = '';

  @override
  Widget build(BuildContext context) {
    final matches = artists.where((a) => a.toLowerCase().contains(search.toLowerCase())).toList();
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: CrossAxisAlignment.start,
      spacing: 8,
      children: [
        Text('Artis', style: ShadTheme.of(context).textTheme.small),
        ShadSelect<String>.withSearch(
          minWidth: 280,
          placeholder: const Text('Pilih artis'),
          searchPlaceholder: const Text('Cari artis'),
          onSearchChanged: (value) => setState(() => search = value),
          options: [
            if (matches.isEmpty)
              const Padding(padding: EdgeInsets.symmetric(vertical: 24), child: Text('Artis tidak ditemukan.')),
            for (final artist in matches) ShadOption(value: artist, child: Text(artist)),
          ],
          selectedOptionBuilder: (context, value) => Text(value),
        ),
      ],
    );
  }
}
```

## Pasang

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/combobox.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/combobox.json
```

## Aksesibilitas

- Input punya `role="combobox"` dan label yang terlihat; daftarnya `role="listbox"` dan itemnya `role="option"`.
- Mengetik menyaring daftar. Tombol panah berpindah antaritem, Enter memilih, dan Escape menutup daftar tanpa mengubah nilai.
- Teks kosong dibacakan saat tidak ada yang cocok.
