Examples & API Integration

Comprehensive examples showing how to integrate mantine-select-async-paginate with real paginated APIs. Learn best practices for handling async data, pagination, and user interactions.

All examples use free, no-authentication APIs for easy testing and integration.

Key Features Demonstrated

Single & Multi-select

Real API Integration

Infinite Scroll

Advanced Customization

Basic Examples

Start with these fundamental examples to understand how AsyncPaginateSelect works with mock data.

Single Select

Basic single-select with pagination, search, and caching.

Select an option

Type to search or scroll to load more options

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

const loadOptions = async (search, loadedOptions, additional) => {
  const response = await fetch(`/api/options?search=${search}&page=${additional?.page || 0}`);
  const data = await response.json();
  
  return {
    options: data.items.map(item => ({
      value: item.id,
      label: item.name
    })),
    hasMore: data.hasMore,
    additional: { page: (additional?.page || 0) + 1 }
  };
};

<AsyncPaginateSelect
  value={value}
  onChange={setValue}
  loadOptions={loadOptions}
  defaultOptions
  cacheOptions
  clearable
/>

Multi-Select (Dedicated Component)

Use AsyncPaginateMultiSelect for dedicated multi-selection functionality.

Select multiple options

Select up to 5 options. Only first 3 shown, rest as +N more

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

<AsyncPaginateMultiSelect
  value={selectedValues}
  onChange={setSelectedValues}
  loadOptions={loadOptions}
  maxSelectedValues={5}
  excludeSelected={true}
  maxDisplayedValues={3}
  defaultOptions
  cacheOptions
/>

Multi-Select (Single Component)

Use the multiple prop on AsyncPaginateSelect for multi-selection mode.

Multiple mode with single component

Using multiple prop. Shows 2 items max, rest as +N more

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

<AsyncPaginateSelect
  multiple={true}
  value={selectedValues}
  onChange={setSelectedValues}
  loadOptions={loadOptions}
  maxSelectedValues={4}
  excludeSelected={true}
/>

Key Features Demonstrated

Pagination: Automatically loads more data when scrolling to bottom

Search: Debounced search with 300ms delay

Caching: Results are cached to avoid unnecessary API calls

Loading States: Built-in loading indicators

Error Handling: Graceful error handling with user feedback

TypeScript: Full TypeScript support with proper typing

Customization: Extensive prop support for customization

Real API Integration Examples

Examples using real, free APIs to demonstrate pagination, search, and data handling. These APIs require no authentication and are perfect for testing and development.

DummyJSON Users (Multi-Select)

limit/skip pagination

search support

208 total users

Real user data with built-in search and pagination from DummyJSON API. Features default loading and search-based filtering.

Select users

Search by name or scroll to load more users

// DummyJSON Users with limit/skip pagination
const loadDummyUsers = async (search, loadedOptions, additional) => {
  const currentSkip = additional?.skip || 0;
  const limit = 10;
  
  let url = `https://dummyjson.com/users?limit=${limit}&skip=${currentSkip}`;
  if (search) {
    url = `https://dummyjson.com/users/search?q=${search}&limit=${limit}&skip=${currentSkip}`;
  }

  const response = await fetch(url);
  const data = await response.json();

  return {
    options: data.users.map(user => ({
      value: user.id.toString(),
      label: `${user.firstName} ${user.lastName}`,
      description: user.email
    })),
    hasMore: currentSkip + limit < data.total,
    additional: { skip: currentSkip + limit }
  };
};

DummyJSON Products (Single-Select)

limit/skip pagination

search support

194 total products

E-commerce product data with pricing, brands, and categories. Demonstrates single-select with rich product information.

Select a product

Search by product name, brand, or category

// DummyJSON Products with search capability
const loadDummyProducts = async (search, loadedOptions, additional) => {
  const currentSkip = additional?.skip || 0;
  const limit = 12;
  
  let url = `https://dummyjson.com/products?limit=${limit}&skip=${currentSkip}`;
  if (search) {
    url = `https://dummyjson.com/products/search?q=${search}&limit=${limit}&skip=${currentSkip}`;
  }

  const response = await fetch(url);
  const data = await response.json();

  return {
    options: data.products.map(product => ({
      value: product.id.toString(),
      label: `${product.title} - $${product.price}`,
      description: `${product.brand} | ${product.category}`
    })),
    hasMore: currentSkip + limit < data.total,
    additional: { skip: currentSkip + limit }
  };
};

ReqRes.in Users (Multi-Select)

page-based pagination

client-side search

12 total users

Clean user data from ReqRes.in with page-based pagination. Search is handled client-side since the API doesn't support search parameters.

Select ReqRes users

Uses page-based pagination with client-side search filtering

// ReqRes.in with page-based pagination
const loadReqresUsers = async (search, loadedOptions, additional) => {
  const currentPage = additional?.page || 1;
  const perPage = 6;

  const response = await fetch(
    `https://reqres.in/api/users?page=${currentPage}&per_page=${perPage}`
  );
  const data = await response.json();

  // Client-side search filtering
  let filteredUsers = data.data;
  if (search) {
    filteredUsers = data.data.filter(user =>
      `${user.first_name} ${user.last_name}`.toLowerCase().includes(search.toLowerCase()) ||
      user.email.toLowerCase().includes(search.toLowerCase())
    );
  }

  return {
    options: filteredUsers.map(user => ({
      value: user.id.toString(),
      label: `${user.first_name} ${user.last_name}`,
      description: user.email
    })),
    hasMore: currentPage < data.total_pages,
    additional: { page: currentPage + 1 }
  };
};

GitHub Repositories (Single-Select)

page-based pagination

server-side search

millions of repos

Search GitHub repositories with star counts and descriptions. Requires minimum 2 characters to search. Results sorted by stars.

Search GitHub repositories

Search returns repositories sorted by star count

// GitHub API with search requirement
const loadGithubRepos = async (search, loadedOptions, additional) => {
  const currentPage = additional?.page || 1;
  
  if (!search || search.length < 2) {
    return { options: [], hasMore: false };
  }

  const response = await fetch(
    `https://api.github.com/search/repositories?q=${search}&page=${currentPage}&per_page=10&sort=stars&order=desc`
  );
  const data = await response.json();

  return {
    options: data.items.map(repo => ({
      value: repo.id.toString(),
      label: repo.full_name,
      description: `⭐ ${repo.stargazers_count} | ${repo.description?.slice(0, 60)}...`
    })),
    hasMore: data.total_count > currentPage * 10,
    additional: { page: currentPage + 1 }
  };
};

API Patterns Comparison

DummyJSON (limit/skip pattern):

?limit=10&skip=20

✅ Built-in search • ✅ Rich data • ✅ Stable pagination

ReqRes.in (page-based pattern):

?page=2&per_page=6

⚠️ Client-side search • ✅ Clean data • ✅ Realistic responses

GitHub API (page-based with search):

?q=react&page=1&per_page=10

✅ Server-side search • ✅ Real-time data • ⚠️ Rate limits

Advanced Features & Configuration

Explore advanced features like custom rendering, load more callbacks, configuration options, and complex API integrations.

Configuration Panel

Adjust these settings to see how they affect the components below.

Debounce Timeout (ms)

Min Search Length

Max Selected Values

Cache Options

Exclude Selected

Load More Triggered:

0 times

Advanced Single Select

Custom Additional Data

Complex Metadata

Request Tracking

Demonstrates advanced loadOptions with complex additional data tracking, custom metadata, and request counting.

Advanced Configuration Demo

Debounce: 300ms | Min search: 2 chars | Cache: ON

// Advanced loadOptions with complex additional data
const loadAdvancedOptions = async (search, loadedOptions, additional) => {
  const currentPage = additional?.page || 0;
  const currentRequests = (additional?.totalRequests || 0) + 1;
  
  // Your complex API logic here...
  
  return {
    options: data.map(item => ({
      value: item.id.toString(),
      label: item.name,
      group: item.category,
      data: item // Store full data for custom rendering
    })),
    hasMore: currentPage < maxPages,
    additional: { 
      page: currentPage + 1,
      timestamp: Date.now(),
      searchQuery: search,
      totalRequests: currentRequests
    }
  };
};

<AsyncPaginateSelect
  loadOptions={loadAdvancedOptions}
  debounceTimeout={300}
  minSearchLength={2}
  onLoadMore={() => console.log('Load more!')}
/>

Advanced Multi Select

Dynamic Configuration

Selection Limits

Exclude Selected

Multi-select with dynamically configurable options. Settings from the configuration panel above are applied here.

Dynamic Configuration Multi-Select

Max selections: 5 | Exclude selected: ON

Custom Option Rendering

Custom Render

Rich Data Display

Multi-line Options

Custom renderOption prop allows you to create rich, multi-line option displays with additional metadata and styling.

Custom Rendered Options

Each option shows category, priority, and creation date

// Custom render option function
const customRenderOption = ({ option, ...others }) => {
  const data = option.data;
  if (!data) return <div {...others}>{option.label}</div>;
  
  return (
    <div {...others} style={{ padding: '8px 12px' }}>
      <div style={{ fontWeight: 500 }}>{option.label}</div>
      <div style={{ fontSize: '0.8rem', color: '#666', marginTop: '2px' }}>
        {data.category} • {data.priority} Priority
      </div>
      <div style={{ fontSize: '0.7rem', color: '#999', marginTop: '2px' }}>
        Created: {new Date(data.created).toLocaleDateString()}
      </div>
    </div>
  );
};

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

JSONPlaceholder Posts

Real API

Offset/Limit Pagination

100 total posts

Real API integration with JSONPlaceholder showing blog posts. Uses offset/limit pagination with client-side search.

JSONPlaceholder Posts

Real blog post data from JSONPlaceholder API

// JSONPlaceholder with offset/limit pagination
const loadJsonPlaceholderPosts = async (search, loadedOptions, additional) => {
  const currentStart = additional?.start || 0;
  const limit = 10;

  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts?_start=${currentStart}&_limit=${limit}`
  );
  const posts = await response.json();
  
  // Client-side search filtering
  const filteredPosts = search 
    ? posts.filter(post => 
        post.title.toLowerCase().includes(search.toLowerCase())
      )
    : posts;

  return {
    options: filteredPosts.map(post => ({
      value: post.id.toString(),
      label: post.title,
      description: post.body.slice(0, 80) + '...'
    })),
    hasMore: posts.length === limit,
    additional: { start: currentStart + limit }
  };
};

Performance & Best Practices

Debouncing: Use appropriate debounce timeout (300ms default) to reduce API calls

Caching: Enable caching for frequently accessed data to improve UX

Minimum Search Length: Set minimum search length for large datasets

Pagination Size: Balance between fewer API calls and faster initial load

Error Handling: Always implement proper error handling in loadOptions

Loading States: Use built-in loading indicators for better UX

Selection Limits: Use maxSelectedValues to prevent performance issues

Customization & Theming

Explore extensive customization options including styling, theming, messages, and custom rendering to match your application's design system.

Customization Controls

Adjust these controls to see how they affect the components below.

Primary Color

Variant

Size

Radius

Loading Message

No Options Message

Load More Text

Styled Single Select

Dynamic Styling

Custom Messages

Mantine Props

Single select with customizable styling, messages, and Mantine component props. All settings from the controls above are applied here.

Customized Theme Selector

Fully customizable styling and messages

// Styled component with custom properties
<AsyncPaginateSelect
  variant="default"
  size="md"
  radius="sm"
  loadingMessage="Loading awesome options..."
  noOptionsMessage="No options found"
  loadMoreText="Load more items"
  styles={{
    input: {
      borderColor: '#228be6',
      '&:focus': {
        borderColor: '#228be6',
        boxShadow: `0 0 0 2px ${primaryColor}20`,
      },
    },
    dropdown: {
      borderColor: '#228be6',
    }
  }}
  loadOptions={loadOptions}
/>

Color-Themed Multi Select

Custom Render

Color Swatches

Grouped Options

Multi-select with custom color rendering, showing color swatches and grouped options. Demonstrates advanced renderOption customization.

Color Palette Selector

Custom color swatches with hex values and categories

// Custom color render with swatches
const colorRenderOption = ({ option, ...others }) => {
  const data = option.data;
  if (!data) return <div {...others}>{option.label}</div>;
  
  return (
    <div {...others} style={{ 
      padding: '8px 12px', 
      display: 'flex', 
      alignItems: 'center', 
      gap: '8px' 
    }}>
      <div style={{ 
        width: '16px', 
        height: '16px', 
        borderRadius: '4px', 
        backgroundColor: data.hex,
        border: '1px solid #ddd',
        flexShrink: 0
      }} />
      <div>
        <div style={{ fontWeight: 500 }}>{option.label}</div>
        <div style={{ fontSize: '0.8rem', color: '#666' }}>
          {data.hex} • {data.category}
        </div>
      </div>
    </div>
  );
};

<AsyncPaginateMultiSelect
  renderOption={colorRenderOption}
  loadOptions={loadColorData}
/>

Message Customization

Custom Messages

Error Handling

Loading States

Demonstrates custom loading, error, and empty state messages. Try different scenarios to see how messages appear.

Message Customization Demo

Custom messages for all interaction states

// Message customization options
<AsyncPaginateSelect
  loadingMessage="Loading awesome options..."
  noOptionsMessage="No options found"
  loadMoreText="Load more items"
  nothingFoundMessage="Try a different search term"
  
  // For error handling in loadOptions:
  loadOptions={async (search, loadedOptions, additional) => {
    try {
      // API call
    } catch (error) {
      // Return empty with error message
      return { 
        options: [], 
        hasMore: false,
        error: { message: 'Failed to load data' }
      };
    }
  }}
/>

Available Mantine Props

All standard Mantine Select/MultiSelect props are supported:

label

placeholder

description

error

required

disabled

variant

size

radius

leftSection

rightSection

styles

classNames

wrapperProps

// Full prop support example
<AsyncPaginateSelect
  // Basic props
  label="Advanced Select"
  placeholder="Type to search..."
  description="With full Mantine prop support"
  error={error}
  required
  disabled={isDisabled}
  
  // Styling props
  variant="filled"
  size="lg"
  radius="md"
  
  // Sections
  leftSection={<IconSearch size="1rem" />}
  rightSection={<IconChevronDown size="1rem" />}
  
  // Custom styling
  styles={{
    input: { fontWeight: 500 },
    dropdown: { border: '2px solid blue' }
  }}
  classNames={{
    input: 'my-custom-input',
    dropdown: 'my-custom-dropdown'
  }}
  
  // Wrapper props
  wrapperProps={{ 'data-testid': 'select-wrapper' }}
  
  // Async props
  loadOptions={loadOptions}
  defaultOptions
  cacheOptions
  multiple={true}
  maxSelectedValues={5}
  excludeSelected={true}
  onLoadMore={() => console.log('Load more')}
/>

Styling Best Practices

Use Mantine's Design System: Leverage built-in variants, sizes, and themes

Custom Styles: Use the styles prop for component-specific customization

CSS-in-JS: Utilize Mantine's emotion-based styling system

Theme Integration: Align with your application's color scheme

Responsive Design: Consider different screen sizes for mobile

Accessibility: Maintain proper contrast ratios and focus states

Performance: Use CSS variables for dynamic theming

Quick API Reference

APIs used in these examples - all free and no authentication required:

DummyJSON

Users, products, posts with built-in pagination

https://dummyjson.com/

ReqRes.in

User management with page-based pagination

https://reqres.in/api/

GitHub API

Repositories, users with Link header pagination

https://api.github.com/

JSONPlaceholder

Posts, users, todos with offset/limit pagination

https://jsonplaceholder.typicode.com/