Select Field

The select field renders a dropdown select with optional search and multi-select support.

Schema Properties

Prop

Type

UI Options

Option	Type	Default	Description
`isClearable`	`boolean`	`true` (when not required)	Show a clear button when a value is selected
`labels`	`object`	-	Text and label overrides
`labels.empty`	`ReactNode`	`"No results found."`	Message shown when no options match
`className`	`string`	-	CSS class applied to the field container
`width`	`string \| number`	-	Inline width applied to the field

React Overrides: The label, description, and ui.labels.empty properties all support ReactNode (JSX) when importing defineSchema from @buildnbuzz/form-react.

Basic Usage

Single Select

const schema = defineSchema({
  fields: [
    {
      type: "select",
      name: "role",
      label: "Role",
      options: [
        { label: "Admin", value: "admin" },
        { label: "User", value: "user" },
        { label: "Guest", value: "guest" },
      ],
      required: true,
    },
  ],
});

Multi-Select

{
  type: "select",
  name: "interests",
  label: "Interests",
  hasMany: true,
  options: ["Design", "Development", "Marketing", "Sales"],
  minSelected: 1,
  maxSelected: 3,
}

Examples

With Clearable Options

{
  type: "select",
  name: "country",
  label: "Country",
  options: countries,
  ui: {
    isClearable: true,
    labels: {
      empty: "No country found",
    },
  },
}

With Option Descriptions

{
  type: "select",
  name: "plan",
  label: "Plan",
  options: [
    { label: "Free", value: "free", ui: { description: "$0/month" } },
    { label: "Pro", value: "pro", ui: { description: "$29/month" } },
    { label: "Enterprise", value: "enterprise", ui: { description: "Custom pricing" } },
  ],
}

With Disabled Options

{
  type: "select",
  name: "region",
  label: "Region",
  options: [
    { label: "US", value: "us" },
    { label: "UK", value: "uk" },
    { label: "EU", value: "eu", disabled: true },
  ],
}

Dynamic Option Disabled

{
  type: "select",
  name: "state",
  label: "State",
  options: [
    { label: "California", value: "CA" },
    { label: "Texas", value: "TX", disabled: { $data: "/country", neq: "US" } },
  ],
}

Async Options with Resolvers

For options loaded from APIs, use the option resolver registry. This enables cascading dropdowns, loading states, and automatic dependency tracking:

const resolvers = defineOptionResolvers({
  listCountries: async () => {
    const res = await fetch("https://countriesnow.space/api/v0.1/countries");
    const json = await res.json();
    return json.data.map((c: { country: string }) => ({
      label: c.country,
      value: c.country,
    }));
  },
});

const schema = defineSchema({
  fields: [
    {
      type: "select",
      name: "country",
      label: "Country",
      options: { resolver: "listCountries" },
    },
  ],
});

// In your form:
<Form schema={schema} optionResolvers={resolvers}>
  <FormContent><FormFields /><FormSubmit /></FormContent>
</Form>

Cascading Dropdowns

Declare dependencies to re-fetch options when a parent field changes:

{
  type: "select",
  name: "state",
  label: "State",
  options: { resolver: "listStates" },
  dependencies: ["/country"],       // re-fetch when country changes
  disabled: { $data: "/country", not: true },  // disable until country selected
}

When a dependency changes, the system automatically:

Clears the field value — prevents stale selections
Re-fetches options — calls the resolver with latest values
Updates loading state — shows loading indicator

See Option Resolvers for the full guide.

Auto-Derived Validators

Property	Validator
`required: true`	`required`
`hasMany: true` + `minSelected`	`minSelected`
`hasMany: true` + `maxSelected`	`maxSelected`

Select Field

On this page