ComboBox

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

Usage

Use standalone, or inside Pagination.

<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.

<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

Other HTMLInputAttributes are passed to <input> via rest props; class is merged onto the root.

Styling

To learn more, see 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

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

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

<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

<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>