API Reference

Complete reference for all components, props, types, and configuration options in mantine-select-async-paginate.

AsyncPaginateSelect

The main component for single-select async pagination. Supports both single and multi-select modes via the `multiple` prop.

import { AsyncPaginateSelect } from 'mantine-select-async-paginate';

<AsyncPaginateSelect
  loadOptions={loadOptions}
  value={value}
  onChange={setValue}
  // ... other props
/>

Props

Prop	Type	Default	Description
`loadOptions` required	`LoadOptionsFunction`	-	Function to load options asynchronously
`value`	`string \| null \| string[]`	`null`	Current selected value(s)
`onChange`	`Function`	-	Callback when value changes
`multiple`	`boolean`	`false`	Enable multi-select mode
`defaultOptions`	`boolean \| ComboboxItem[]`	`false`	Load options on mount or provide default options
`cacheOptions`	`boolean`	`false`	Cache loaded options
`debounceTimeout`	`number`	`300`	Debounce timeout in milliseconds
`minSearchLength`	`number`	`0`	Minimum characters to trigger search
`maxSelectedValues`	`number`	-	Maximum selections allowed (multi-select only)
`excludeSelected`	`boolean`	`true`	Hide selected options from dropdown (multi-select only)
`loadingMessage`	`string`	`"Loading..."`	Message shown while loading
`noOptionsMessage`	`string`	`"No options"`	Message shown when no options found
`loadMoreText`	`string`	`"Load more..."`	Text for load more button
`onLoadMore`	`() => void`	-	Callback when load more is triggered
`renderOption`	`Function`	-	Custom option renderer
`additional`	`any`	-	Additional data passed to loadOptions

All standard Mantine Select props are also supported (label, placeholder, error, disabled, etc.)

AsyncPaginateMultiSelect

Dedicated component for multi-select async pagination with enhanced features.

import { AsyncPaginateMultiSelect } from 'mantine-select-async-paginate';

<AsyncPaginateMultiSelect
  loadOptions={loadOptions}
  value={values}
  onChange={setValues}
  maxSelectedValues={5}
  excludeSelected={true}
  // ... other props
/>

Props

AsyncPaginateMultiSelect supports all the same props as AsyncPaginateSelect (except `multiple`), with these differences:

value is always string[]
onChange receives (values: string[]) => void
maxSelectedValues and excludeSelected are commonly used
All Mantine MultiSelect props are supported

Type Definitions

LoadOptionsFunction

type LoadOptionsFunction<Additional = any> = (
  search: string,
  loadedOptions: ComboboxItem[],
  additional?: Additional
) => Promise<LoadOptionsResult<Additional>>;

LoadOptionsResult

interface LoadOptionsResult<Additional = any> {
  options: ComboboxItem[];
  hasMore: boolean;
  additional?: Additional;
}

ComboboxItem

interface ComboboxItem {
  value: string;
  label: string;
  disabled?: boolean;
  group?: string;
  description?: string;
  data?: any; // Custom data for renderOption
}

AsyncPaginateSelectProps

type AsyncPaginateSelectProps<Additional = any> = 
  | SingleSelectProps<Additional> 
  | MultiSelectProps<Additional>;

// Single select mode
interface SingleSelectProps extends BaseProps {
  multiple?: false;
  value?: string | null;
  onChange?: (value: string | null, option: ComboboxItem | null) => void;
}

// Multi select mode
interface MultiSelectProps extends BaseProps {
  multiple: true;
  value?: string[];
  onChange?: (value: string[]) => void;
}

Generic Types

The components support TypeScript generics for the `additional` parameter:

// Define your additional data type
interface MyAdditional {
  page: number;
  filters: string[];
  sortBy: string;
}

// Use with the component
<AsyncPaginateSelect<MyAdditional>
  loadOptions={async (search, loaded, additional) => {
    // additional is typed as MyAdditional | undefined
    const page = additional?.page || 1;
    // ...
  }}
  additional={{ page: 1, filters: [], sortBy: 'name' }}
/>

useAsyncOptions Hook

Low-level hook for implementing custom async select components. This hook is used internally by AsyncPaginateSelect.

import { useAsyncOptions } from 'mantine-select-async-paginate';

const {
  options,      // Current loaded options
  loading,      // Loading state
  error,        // Error state
  hasMore,      // Whether more data is available
  loadMore,     // Function to load more options
  handleSearch, // Function to handle search
} = useAsyncOptions({
  loadOptions,
  defaultOptions,
  cacheOptions,
  debounceTimeout,
  additional,
  minSearchLength,
});

Hook Parameters

Parameter	Type	Description
`loadOptions`	`LoadOptionsFunction`	Function to load options
`defaultOptions`	`boolean \| ComboboxItem[]`	Initial options
`cacheOptions`	`boolean`	Enable caching
`debounceTimeout`	`number`	Debounce delay
`additional`	`any`	Additional data
`minSearchLength`	`number`	Min search length

Custom Component Example

function CustomAsyncSelect() {
  const {
    options,
    loading,
    hasMore,
    loadMore,
    handleSearch,
  } = useAsyncOptions({
    loadOptions: myLoadFunction,
    defaultOptions: true,
    cacheOptions: true,
  });

  return (
    <div>
      <input onChange={(e) => handleSearch(e.target.value)} />
      {loading && <span>Loading...</span>}
      <ul>
        {options.map(option => (
          <li key={option.value}>{option.label}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore}>Load More</button>
      )}
    </div>
  );
}

Common Patterns

Error Handling

const loadOptions = async (search, loadedOptions, additional) => {
  try {
    const response = await fetch(`/api/search?q=${search}`);
    if (!response.ok) throw new Error('Failed to fetch');
    
    const data = await response.json();
    return {
      options: data.items.map(item => ({
        value: item.id,
        label: item.name
      })),
      hasMore: data.hasMore
    };
  } catch (error) {
    console.error('Error loading options:', error);
    return { options: [], hasMore: false };
  }
};

Custom Render Option

const renderOption = ({ option, ...others }) => (
  <div {...others} style={{ padding: '8px 12px' }}>
    <div style={{ fontWeight: 500 }}>{option.label}</div>
    {option.description && (
      <div style={{ fontSize: '0.8rem', color: '#666' }}>
        {option.description}
      </div>
    )}
  </div>
);

<AsyncPaginateSelect
  renderOption={renderOption}
  loadOptions={loadOptions}
/>