# ComboBox

A combination of a text input and dropdown that allows typing to filter options.

## Usage

Use standalone, or inside `Pagination`.

```svelte
<ComboBox {...props} />

<Pagination>
  <ComboBox {...props} />
</Pagination>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<span class="whole" style>
  <input class="main" {...rest} type="text" bind:value bind:this={element} />
  <div class="extra" conditional>{extra}</div>
  <ul class="bottom">
    {#each options as option}
      <li class="label">{option}</li>
    {/each}
  </ul>
</span>
```

## Props

| Name       | Type               | Default   | Description                                                             |
| ---------- | ------------------ | --------- | ----------------------------------------------------------------------- |
| `options`  | `SvelteSet`        | -         | Values displayed as selectable options; empty options prevent rendering |
| `extra`    | `Snippet`          | -         | Extra content; receives expanded state and variant                      |
| `value`    | `string`           | -         | Bindable input value                                                    |
| `expanded` | `boolean`          | -         | Bindable listbox open state                                             |
| `search`   | `boolean`          | `true`    | Enables forward-matching search; set false for very large option sets   |
| `cssvar`   | `object`           | -         | Custom-property names for the listbox x/y offsets and z-index; absent key uses the default name |
| `attach`   | `Attachment`       | -         | Svelte attachment on the input                                          |
| `element`  | `HTMLInputElement` | -         | Bindable input element                                                  |
| `styling`  | `SVSClass`         | -         | Styling override                                                        |
| `variant`  | `SVSVariant`       | `NEUTRAL` | Variant                                                                 |
Other `HTMLInputAttributes` are passed to `<input>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

The currently selected option will apply the `active`. `ul` element as `bottom` (listbox) will apply the `active` when expanded. Others are not automatically switched.

### Default Class Name

`svs-combo-box`

## Behavior

- When embedded in a `ComboBoxContext`, `options`, `value`, `variant`, and fallback `styling` come from the context.
- Closing the listbox invokes the context's `commit` hook when present.
- The `whole` wrapper is `position:relative;display:inline-block;` because the listbox anchors against it; a caller overriding its `display` owns the resulting anchor geometry.
- The listbox defaults below/left, flips per axis above/right on viewport overflow, exposes `data-svs-flip-x` / `data-svs-flip-y` on flipped axes, and reads its offsets from `cssvar` x/y custom properties (defaults `--svs-position-x` / `--svs-position-y`).
- The listbox carries `z-index: var(--svs-position-z, 1)` so it paints above adjacent positioned content. Override it from caller CSS or rename it via the `cssvar` z key to fit a caller's own stacking order.

Open/close animations should be layered on the `bottom` part variant classes (`active` = open) with opacity, transform, or scale; the component keeps `visibility` as its structural default.

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowDown` | When closed, opens the listbox and highlights the current value if it is one of the options, otherwise the first option; when open, moves the highlight down one option |
| `ArrowUp` | When closed, opens the listbox and highlights the current value if it is one of the options, otherwise the last option; when open, moves the highlight up one option |
| `Alt` + `ArrowDown` | Opens the listbox, highlighting the current value if it is one of the options (otherwise no option is highlighted) |
| `Alt` + `ArrowUp` | Closes the open listbox |
| `Enter` | Selects the highlighted option, fills the input, and closes the listbox |
| `Escape` | Closes the open listbox |
Typing filters the options by forward match (see the `search` prop).

### ARIA Roles and Attributes

The component applies these automatically:

- Input (`main`): `role="combobox"`, `aria-haspopup="listbox"`, `aria-autocomplete="list"`, `aria-controls` (the listbox), `aria-expanded` (open state), and `aria-activedescendant` (the highlighted option).
- Listbox (`bottom` `<ul>`): `role="listbox"`.
- Option (`label` `<li>`): `role="option"`, with `aria-selected` on the highlighted option.

Provide an accessible name yourself because there is no built-in visible label. Pass `aria-label` or `aria-labelledby` through the rest props, or associate a `<label>` with the input. The managed ARIA attributes above are omitted from `ComboBoxProps` and cannot be overridden.

## Exports

### Types

```ts
interface ComboBoxProps extends Omit<
  HTMLInputAttributes,
  "type" | "value" | "list" | "role" | "aria-haspopup" | "aria-autocomplete" | "aria-controls" | "aria-expanded" | "aria-activedescendant"
> {
  options?: SvelteSet<string> | Set<string>;
  extra?: Snippet<[boolean, string]>; // Snippet<[expanded,variant]>
  value?: string; // bindable
  expanded?: boolean; // bindable
  search?: boolean; // (true)
  cssvar?: Partial<Record<ComboBoxCssVar, string>>; // custom-property names for the listbox x/y offsets and z-index; absent key uses default name
  attach?: Attachment<HTMLInputElement>;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // class & other HTMLInputAttributes are passed to <input> via ...rest
}
type ComboBoxCssVar = "x" | "y" | "z";
type ComboBoxReqdProps = never;
type ComboBoxBindProps = "value" | "expanded" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ComboBoxBasic.svelte
<script lang="ts">
  import { ComboBox } from "svseeds";

  const styling = {
    main: "px-2 py-1 rounded-sm border outline-hidden",
    bottom: "w-full border border-gray-400 bg-white dark:bg-black",
    label: {
      base: "px-2",
      active: "bg-gray-400",
    },
  };
  const myProps = {
    options: new Set(["HTML", "CSS", "JavaScript", "TypeScript"]),
    styling,
  };
</script>

<ComboBox {...myProps} />
```
### With Interactive Variant

**Code**

```svelte src=ComboBoxPract.svelte
<script lang="ts">
  import { ComboBox } from "svseeds";
  import ChevronDown from "@lucide/svelte/icons/chevron-down";

  let { variant = $bindable() } = $props();
  const variantStyle1 = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const variantStyle2 = {
    neutral: "opacity-0",
    active: "opacity-100",
  };
  const styling = {
    main: {
      base: "px-2 py-1 border-b outline-hidden",
      ...variantStyle1,
    },
    extra: "px-2",
    bottom: {
      base: "-mt-px py-1 w-full rounded-sm border border-gray-600 bg-white dark:bg-black transition-opacity duration-150",
      ...variantStyle2,
    },
    label: {
      base: "px-2 rounded-sm",
      active: "bg-gray-200 dark:bg-gray-700",
    },
  };
  const myProps = {
    options: new Set(["HTML", "CSS", "JavaScript", "TypeScript"]),
    styling,
  };
</script>

<ComboBox {variant} {...myProps}>
  {#snippet extra(expanded: boolean)}
    <div class={["size-fit transition-[scale] duration-400", { "-scale-y-100": expanded }]}>
      <ChevronDown class="size-5" />
    </div>
  {/snippet}
</ComboBox>
```