@zealamic/react-dynamic-select

Async select components for React — fetch options from an API, search, paginate, and load more. Works with Ant Design, MUI, Chakra UI, Base UI (styled defaults included), or your own UI via headless hooks.

Features

• Async data — fetch options on open or mount, with configurable API params
• Search — inline (main input) or menu (dropdown input), with debounce
• Load more — scroll-to-bottom or click-to-load pagination
• Add button — optional create action in the dropdown footer
• Custom option labels — string templates or React components per row
• Multiple selection — single and multi-select support with dismissible chips
• Pre-loaded values — display selected items in edit mode via currentData
• Base UI defaults — styled Combobox UI out of the box; override slots when needed
• Type-safe — full TypeScript generics for API response, params, and data models

Preview

Same dynamicConfig across UI libraries:

Ant Design	MUI

Base UI	Chakra UI

More screenshots and usage details in the documentation.

Installation

npm

npm install @zealamic/react-dynamic-select

yarn

yarn add @zealamic/react-dynamic-select

pnpm

pnpm add @zealamic/react-dynamic-select

Also install the UI library for your entry point. Each guide has npm, yarn, and pnpm commands — see Documentation or the table below.

Peer dependencies: react >= 19. UI libraries are optional.

Documentation

Guide	Description
Ant Design	AntdDynamicSelect, useAntdDynamicSelect
MUI	MuiDynamicSelect, useMuiDynamicSelect
Chakra UI	ChakraDynamicSelect, useChakraDynamicSelect
Base UI	BaseUiDynamicSelect, createDefaultBaseUiComponents, slots
Build your own	Headless hooks, utilities, custom UI

Quick example

import { AntdDynamicSelect } from "@zealamic/react-dynamic-select/antd";

<AntdDynamicSelect
  placeholder="Select a user"
  showSearch
  allowClear
  dynamicConfig={{
    api: {
      fetch: fetchUsers,
      params: { page: 1, pageSize: 10, search: "" },
    },
    list: { path: "data" },
    total: { path: "total" },
    option: { template: { label: "fullName", value: "id" } },
  }}
/>;

All variants share the same dynamicConfig shape. Pass only the fields that differ from the defaults.

Chakra UI — wrap your app with ChakraProvider, then use the same config:

import { ChakraProvider, defaultSystem } from "@chakra-ui/react";
import { ChakraDynamicSelect } from "@zealamic/react-dynamic-select/chakra";

<ChakraProvider value={defaultSystem}>
  <ChakraDynamicSelect
    placeholder="Select a user"
    width="320px"
    dynamicConfig={userListConfig}
  />
</ChakraProvider>;

Base UI works without a components prop — defaults are styled and ready to use. Customize with createDefaultBaseUiComponents():

import { BaseUiDynamicSelect } from "@zealamic/react-dynamic-select/base-ui";

<BaseUiDynamicSelect
  placeholder="Select a user"
  listHeight={200}
  dynamicConfig={userListConfig}
/>;

Option template — string label

option.template.label as a string maps each API item to the option text. Three forms are supported:

1. Field path — read a property from the item (supports dot notation for nested fields):

// API item: { id: 1, fullName: "John Doe" }
option: {
  template: {
    label: "fullName", // → "John Doe"
    value: "id",       // → 1
  },
}

// Nested: { id: 1, profile: { name: "John Doe" } }
option: {
  template: {
    label: "profile.name", // → "John Doe"
    value: "id",
  },
}

2. Placeholder template — combine multiple fields in one label:

// API item: { id: 1, firstName: "John", lastName: "Doe" }
option: {
  template: {
    label: "{firstName} {lastName}", // → "John Doe"
    value: "id",
  },
}

Use {field} or {nested.field} placeholders. Missing values render as empty strings in the label.

3. Full example with dynamicConfig:

const userListConfig = {
  api: { fetch: fetchUsers, params: { page: 1, pageSize: 10, search: "" } },
  list: { path: "data" },
  total: { path: "total" },
  option: {
    template: {
      label: "fullName", // or "{firstName} {lastName}"
      value: "id",
    },
  },
};

option.template.value uses the same field-path rules to pick the option id stored in the select.

Option template — React component label

Custom option label — use a React component instead of a string field or template. Screenshots and per-UI examples are in the Custom option label section of each UI guide — see Documentation.

option: {
  template: {
    label: ({ data }) => (
      <span>
        {data.firstName} {data.lastName}
      </span>
    ),
    value: "id",
  },
}

The resolved label is a ReactNode in the option list. String-based helpers such as getOptionLabel fall back to value when the label is not plain text.

Dynamic config properties

dynamicConfig is the shared prop that wires async behavior into every variant. It is deep-merged with defaultDynamicSelectConfig — you only need to pass fields that differ from the defaults.

Property	Description	Type	Default
api	API fetch configuration	object	—
api.fetch	Function that loads options from the server	(params) => Promise<ApiResponse>	—
api.params	Default query sent on every request (page, pageSize or limit, search)	ApiParams & PaginationParams	{ page: 1, pageSize: 10, search: "" }
api.trigger	When to run the first fetch	"open" | "mount"	"open"
api.onSuccess	Called after a successful fetch	(data: ApiResponse) => void	—
api.onError	Called when a fetch fails	(error: Error) => void	—
list	Maps the options array from the API response	object	—
list.path	Dot path to the list in the response, e.g. "data" or "result.items"	string	"list"
total	Maps the total record count from the response	object	—
total.path	Dot path to the total count, e.g. "total"	string	"total"
total.label	Label shown in the dropdown footer	string	"Total"
option	Maps each API item to a select option	object	—
option.template.label	Label field, placeholder template ("{firstName} {lastName}"), or React component ({ data }) => ReactNode	string | FC<{ data: DataType }>	"label"
option.template.value	Value field	string	"value"
currentData	Pre-loaded item(s) for edit mode when the selected value is not in the fetched list yet	DataType | DataType[]	—
search	Search input configuration	object	—
search.placement	Where the search input is rendered	"menu" | "inline"	"menu"
search.debounce	Debounce delay before triggering a search fetch (ms)	number	500
search.inputSearchMenuProps	Props for the menu search input (Ant Design Input, MUI TextField, Chakra/Base UI ComboboxInput)	InputSearchProps	{ placeholder: "Search..." }
loadMore	Enable pagination / load more. true enables click mode with defaults	boolean | object	{ type: "click", threshold: 100, distance: 100, debounce: 100 }
loadMore.type	How to load the next page	"click" | "scroll"	"click"
loadMore.label	Load-more button text	string	"Load More"
loadMore.loadingLabel	Text shown while loading more	string	"Loading..."
loadMore.threshold	Scroll threshold (px) to trigger load more	number	100
loadMore.distance	Distance from bottom (px) to trigger scroll load more	number	100
loadMore.debounce	Debounce delay for scroll load more (ms)	number	100
loadMore.afterFetch	Hook called after each successful fetch	(data: ApiResponse) => Promise<void>	—
add	Add button in the dropdown footer (e.g. create a new record)	object	—
add.label	Button label text	string	—
add.icon	Custom icon before the label	ReactNode	built-in plus icon
add.placement	Footer position of the add button	"start" | "end"	—
add.onClick	Called when the add button is clicked	() => void	—
add.disabled	Disables the add button	boolean	false
messages	Loading and empty-state copy in the dropdown	object	—
messages.loading	Shown while the initial fetch is in progress with an empty list (Base UI overlay; MUI loadingText fallback)	ReactNode | null	"Loading..."
messages.empty	Shown when the list is empty and there is no active search	ReactNode | null	"No items found"
messages.noResults	Shown when the list is empty after searching	ReactNode | null	"No results found."

---

License

MIT

---

If this library saves you time building async selects, thanks for using it.