Combobox Field

A labeled combobox input with a filtered popup of selectable items and helper or error text.

Basic

Region

Filter the deployment region.

Show code

import { ComboboxField } from "@makeplane/propel/components/combobox-field";
import { Icon } from "@makeplane/propel/components/icon";
import { IconButton } from "@makeplane/propel/components/icon-button";
import { ChevronsUpDown, X } from "lucide-react";

const REGIONS = ["us-central-1", "us-east-1", "eu-central-1", "ap-west-1"];

export default function BasicDemo() {
  return (
    <ComboboxField
      name="region"
      label="Region"
      description="Filter the deployment region."
      magnitude="md"
      items={REGIONS}
      placeholder="e.g. eu-central-1"
      empty="No regions found"
      clear={
        <IconButton
          prominence="ghost"
          tone="neutral"
          magnitude="md"
          aria-label="Clear region"
          icon={<Icon icon={X} />}
        />
      }
      trigger={
        <IconButton
          prominence="ghost"
          tone="neutral"
          magnitude="md"
          aria-label="Open region"
          icon={<Icon icon={ChevronsUpDown} />}
        />
      }
    />
  );
}

Magnitudes

Magnitude steps the label, description, and helper-text sizes; the input group itself stays fixed.

Filter the deployment region.

Show code

import { ComboboxField } from "@makeplane/propel/components/combobox-field";
import { Icon } from "@makeplane/propel/components/icon";
import { IconButton } from "@makeplane/propel/components/icon-button";
import { ChevronsUpDown, X } from "lucide-react";

const REGIONS = ["us-central-1", "us-east-1", "eu-central-1", "ap-west-1"];
const MAGNITUDES = ["md", "lg", "xl"] as const;

export default function MagnitudesDemo() {
  return (
    <div className="flex flex-col gap-4">
      {MAGNITUDES.map((magnitude) => (
        <ComboboxField
          key={magnitude}
          name={`region-${magnitude}`}
          label={magnitude}
          description="Filter the deployment region."
          magnitude={magnitude}
          items={REGIONS}
          placeholder="e.g. eu-central-1"
          empty="No regions found"
          clear={
            <IconButton
              prominence="ghost"
              tone="neutral"
              magnitude="md"
              aria-label="Clear region"
              icon={<Icon icon={X} />}
            />
          }
          trigger={
            <IconButton
              prominence="ghost"
              tone="neutral"
              magnitude="md"
              aria-label="Open region"
              icon={<Icon icon={ChevronsUpDown} />}
            />
          }
        />
      ))}
    </div>
  );
}

Invalid

Setting error marks the field invalid, recoloring the input group border and replacing the description with the error text.

Region

Choose a deployment region.

Show code

import { ComboboxField } from "@makeplane/propel/components/combobox-field";
import { Icon } from "@makeplane/propel/components/icon";
import { IconButton } from "@makeplane/propel/components/icon-button";
import { ChevronsUpDown, X } from "lucide-react";

const REGIONS = ["us-central-1", "us-east-1", "eu-central-1", "ap-west-1"];

export default function InvalidDemo() {
  return (
    <ComboboxField
      name="region"
      label="Region"
      error="Choose a deployment region."
      magnitude="md"
      items={REGIONS}
      placeholder="e.g. eu-central-1"
      empty="No regions found"
      clear={
        <IconButton
          prominence="ghost"
          tone="neutral"
          magnitude="md"
          aria-label="Clear region"
          icon={<Icon icon={X} />}
        />
      }
      trigger={
        <IconButton
          prominence="ghost"
          tone="neutral"
          magnitude="md"
          aria-label="Open region"
          icon={<Icon icon={ChevronsUpDown} />}
        />
      }
    />
  );
}

Disabled

Region

Filter the deployment region.

Show code

import { ComboboxField } from "@makeplane/propel/components/combobox-field";
import { Icon } from "@makeplane/propel/components/icon";
import { IconButton } from "@makeplane/propel/components/icon-button";
import { ChevronsUpDown, X } from "lucide-react";

const REGIONS = ["us-central-1", "us-east-1", "eu-central-1", "ap-west-1"];

export default function DisabledDemo() {
  return (
    <ComboboxField
      name="region"
      label="Region"
      description="Filter the deployment region."
      magnitude="md"
      disabled
      items={REGIONS}
      placeholder="e.g. eu-central-1"
      empty="No regions found"
      clear={
        <IconButton
          prominence="ghost"
          tone="neutral"
          magnitude="md"
          aria-label="Clear region"
          icon={<Icon icon={X} />}
        />
      }
      trigger={
        <IconButton
          prominence="ghost"
          tone="neutral"
          magnitude="md"
          aria-label="Open region"
          icon={<Icon icon={ChevronsUpDown} />}
        />
      }
    />
  );
}

Installation

import { ComboboxField } from "@makeplane/propel/components/combobox-field";

Props

ComboboxField

Prop	Type	Required	Description
autoComplete	string	No	Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
autoHighlight	boolean	No	Whether the first matching item is highlighted automatically while filtering.
highlightItemOnHover	boolean	No	Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
itemToStringLabel	((itemValue: Value) => string)	No	When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
itemToStringValue	((itemValue: Value) => string)	No	When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
isItemEqualToValue	((itemValue: Value, value: Value) => boolean)	No	Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison.
actionsRef	RefObject<Actions \| null>	No	A ref to imperative actions. - `unmount`: Manually unmounts the combobox. Call this after any externally controlled closing animation finishes.
onOpenChange	((open: boolean, eventDetails: ChangeEventDetails) => void)	No	Event handler called when the popup is opened or closed.
onInputValueChange	((inputValue: string, eventDetails: ChangeEventDetails) => void)	No	Event handler called when the input value changes.
onItemHighlighted	((highlightedValue: Value, eventDetails: HighlightEventDetails) => void)	No	Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. - `'none'`: the highlight changed programmatically.
multiple	false	No	Whether multiple items can be selected.
defaultValue	Value \| null	No	The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead.
value	Value \| null	No	The selected value of the combobox. Use when controlled.
onValueChange	((value: Value \| null, eventDetails: ChangeEventDetails) => void)	No	Event handler called when the selected value of the combobox changes.
description	ReactNode	No	Supporting text shown below the input. Replaced by `error` when an error is set.
clear	ReactElement<unknown, string \| JSXElementConstructor<any>>	Yes	The clear control (e.g. an `IconButton`), rendered as the combobox's clear button. It carries its own — localizable — `aria-label`; the field bakes no label text.
trigger	ReactElement<unknown, string \| JSXElementConstructor<any>>	Yes	The popup-trigger control (e.g. an `IconButton`), rendered as the combobox's trigger. It carries its own — localizable — `aria-label`; the field bakes no label text.
empty	ReactNode	Yes	Message rendered when no item matches.
error	ReactNode	No	Error text shown below the control.
hint	ReactNode	No	Helper text shown below the control. Replaced by `error` when an error is set.
items	readonly Value[]	Yes	Items rendered in the popup.
label	string	Yes	Visible field label.
magnitude	"md" \| "lg" \| "xl"	Yes	Label and helper text size.
placeholder	string	No	Input placeholder.