Fluxo UIFluxo UIv0.4.1

Multiselect

A powerful multiselect component for choosing multiple options with search, selection limits, and bulk operations.

Basic Usage

Basic Multiselect

ReactTypeScript
Basic Example
import { Multiselect } from 'fluxo-ui';

function MyComponent() {
  const [values, setValues] = useState(['react', 'typescript']);

  const options = [
    { label: 'React', value: 'react' },
    { label: 'Vue.js', value: 'vue' },
    { label: 'Angular', value: 'angular' },
    { label: 'TypeScript', value: 'typescript' },
    // ... more options
  ];

  return (
    <Multiselect
      label="Technologies"
      placeholder="Select technologies..."
      options={options}
      value={values}
      onChange={setValues}
    />
  );
}

Selection Limit

Maximum 3 Selections

RedBlue
<Multiselect
  label="Favorite Colors (Max 3)"
  placeholder="Choose up to 3 colors..."
  options={colorOptions}
  value={values}
  onChange={setValues}
  maxSelections={3}
/>

Select All Option

Multiselect with Select All

Select your skills...
<Multiselect
  label="Skills"
  placeholder="Select your skills..."
  options={skillOptions}
  value={values}
  onChange={setValues}
  showSelectAll
/>

Grouped Options

Multiselect with Grouped Items

ReactNode.js
const groupedOptions = [
  {
    label: 'Frontend',
    items: [
      { label: 'React', value: 'react' },
      { label: 'Vue.js', value: 'vue' },
      { label: 'Angular', value: 'angular' },
      { label: 'Svelte', value: 'svelte' },
    ],
  },
  {
    label: 'Backend',
    items: [
      { label: 'Node.js', value: 'nodejs' },
      { label: 'Django', value: 'django' },
      { label: 'Spring Boot', value: 'spring' },
      { label: 'Laravel', value: 'laravel' },
    ],
  },
  {
    label: 'Mobile',
    items: [
      { label: 'React Native', value: 'react-native' },
      { label: 'Flutter', value: 'flutter' },
      { label: 'Swift', value: 'swift', disabled: true },
    ],
  },
];

<Multiselect
  label="Technologies"
  placeholder="Select technologies..."
  options={groupedOptions}
  value={values}
  onChange={setValues}
  showSelectAll={false}
/>

Custom Field Mapping

Multiselect with optionLabel / optionValue

United StatesGermany
const countries = [
  { name: 'United States', code: 'US' },
  { name: 'Canada', code: 'CA' },
  { name: 'United Kingdom', code: 'UK' },
  { name: 'Germany', code: 'DE' },
];

<Multiselect
  label="Countries"
  placeholder="Select countries..."
  options={countries}
  optionLabel="name"
  optionValue="code"
  value={values}
  onChange={setValues}
/>

States

Multiselect States

Normal state
RedBlue
Disabled state
Required field
Select at least one
<Multiselect label="Normal" placeholder="Normal state" options={options} />
<Multiselect label="With Selections" options={options} value={['red', 'blue']} onChange={setValues} />
<Multiselect label="Disabled" placeholder="Disabled state" options={options} disabled />
<Multiselect label="Read Only" options={options} value={['green', 'yellow']} readonly />
<Multiselect label="Required" placeholder="Required field" options={options} required />
<Multiselect label="With Error" options={options} error="Please select at least one option" />

Import

import { Multiselect } from 'fluxo-ui';

Props

value
any[]

Array of currently selected values (controlled component)

optionsreq
ListItem[] | ListItemGroup[]

Flat array of items or grouped items. Each group has a label, optional icon, and an items array.

onChange
function

Change event handler called with {event, value, name, args}

onFilter
function

Called when filter value changes: (query: string) => void | Promise<void>

placeholder
string

Placeholder text when no options are selected

label
string

Label text for the multiselect

error
string

Error message to display

disabled
booleanfalse

Disable the multiselect

readonly
booleanfalse

Make the multiselect read-only

required
booleanfalse

Mark the multiselect as required

searchable
booleantrue

Enable search/filter functionality

debounceMs
number300

Debounce delay in milliseconds for filter input

maxSelectedItems
number

Maximum number of selections allowed

loading
booleanfalse

Show loading state

emptyMessage
string"No items available"

Message to display when no options are available

showSelectAll
booleantrue

Show select all / deselect all option

renderItem
function

Custom render function for items: (item, index, isSelected, isHighlighted) => ReactNode

renderSelectedItem
function

Custom render function for selected items: (item, onRemove) => ReactNode

id
string

HTML id attribute for the input element

name
string

HTML name attribute for form submission

args
any

Custom arguments passed to onChange event

optionLabel
string"label"

Property name to use as the display label from each option object

optionValue
string"value"

Property name to use as the value from each option object

className
string

Additional CSS classes

Features

Multi-Selection

Select multiple values at once with tag-style display of selected items

Built-in Search

Debounced filter input to quickly find options within large lists

Grouped Options

Organize options into labeled groups for better navigation

Selection Limit

Enforce a maximum number of selections with the maxSelectedItems prop

Select All

One-click bulk select and deselect all visible options

Custom Field Mapping

Use optionLabel and optionValue to work with any data shape

Async Filtering

onFilter callback supports async data loading with built-in debounce

Accessibility

Keyboard navigation, ARIA roles, and focus management built in

Theming

Full dark/light and 5 brand themes supported via CSS variables