arkyn

v3.0.1-beta.72

MultiSelect

The MultiSelect component allows users to select multiple options from a dropdown list. It offers advanced features like search, loading, validation, and different visual variants. It's ideal for cases where multiple selections are needed.

tsx

import { MultiSelect } from "@arkyn/components";

Basic Usage

Basic usage requires the name and options properties. Options must be an array of objects with label and value.

tsx

<MultiSelect
  name="basic-multi"
  options={[
    { label: "JavaScript", value: "js" },
    { label: "TypeScript", value: "ts" },
    { label: "Python", value: "python" },
    { label: "Java", value: "java" },
  ]}
/>

Sizes

Available sizes are md and lg, with md being the default.

tsx

<MultiSelect
  name="multi-md"
  label="Medium size"
  size="md"
  options={[
    { label: "Option 1", value: "opt1" },
    { label: "Option 2", value: "opt2" },
    { label: "Option 3", value: "opt3" }
  ]}
/>


<MultiSelect
  name="multi-lg"
  label="Large size"
  size="lg"
  options={[
    { label: "Option 1", value: "opt1" },
    { label: "Option 2", value: "opt2" },
    { label: "Option 3", value: "opt3" }
  ]}
/>

Variants

Available variants are solid, outline and underline, providing different visual styles.

tsx

<MultiSelect
  name="multi-solid"
  label="Solid variant"
  variant="solid"
  options={[
    { label: "Design", value: "design" },
    { label: "Frontend", value: "frontend" },
    { label: "Backend", value: "backend" }
  ]}
/>


<MultiSelect
  name="multi-outline"
  label="Outline variant"
  variant="outline"
  options={[
    { label: "Design", value: "design" },
    { label: "Frontend", value: "frontend" },
    { label: "Backend", value: "backend" }
  ]}
/>


<MultiSelect
  name="multi-underline"
  label="Underline variant"
  variant="underline"
  options={[
    { label: "Design", value: "design" },
    { label: "Frontend", value: "frontend" },
    { label: "Backend", value: "backend" }
  ]}
/>

MultiSelect with Icon

Add icons to enhance visual and contextual experience.

tsx

<MultiSelect
  name="multi-with-icon"
  label="Technologies"
  leftIcon={Code}
  options={[
    { label: "React", value: "react" },
    { label: "Vue", value: "vue" },
    { label: "Angular", value: "angular" },
    { label: "Svelte", value: "svelte" },
  ]}
/>

Prefix

Use prefix to add text or icon at the beginning of the field.

tsx

<MultiSelect
  name="multi-prefix-text"
  label="Departments"
  prefix="Dept:"
  options={[
    { label: "Human Resources", value: "hr" },
    { label: "Technology", value: "tech" },
    { label: "Marketing", value: "marketing" },
    { label: "Sales", value: "sales" },
  ]}
/>

Searchable MultiSelect

Enable search functionality with isSearchable to facilitate selection in large lists.

tsx

<MultiSelect
  name="searchable-multi"
  label="Cities"
  isSearchable
  placeholder="Search and select cities..."
  notFoundText="No cities found"
  leftIcon={MapPin}
  options={[
    { label: "New York", value: "ny" },
    { label: "Los Angeles", value: "la" },
    { label: "Chicago", value: "chicago" },
    { label: "Houston", value: "houston" },
    { label: "Phoenix", value: "phoenix" },
    { label: "Philadelphia", value: "philadelphia" },
    { label: "San Antonio", value: "sanantonio" },
    { label: "San Diego", value: "sandiego" },
  ]}
/>

Default Values

Use defaultValue to pre-select specific options.

tsx

<MultiSelect
  name="default-values"
  label="Skills"
  defaultValue={["js", "react"]}
  leftIcon={Code}
  options={[
    { label: "JavaScript", value: "js" },
    { label: "TypeScript", value: "ts" },
    { label: "React", value: "react" },
    { label: "Vue", value: "vue" },
    { label: "Node.js", value: "node" },
    { label: "Python", value: "python" },
  ]}
/>

Close Behavior

Configure when the dropdown should close after a selection with closeOnSelect.

tsx

<MultiSelect
  name="close-on-select"
  label="Tags (closes on select)"
  closeOnSelect={true}
  leftIcon={Tag}
  options={[
    { label: "React", value: "react" },
    { label: "JavaScript", value: "js" },
    { label: "CSS", value: "css" },
    { label: "HTML", value: "html" }
  ]}
/>


<MultiSelect
  name="keep-open"
  label="Categories (keeps open)"
  closeOnSelect={false}
  leftIcon={Tag}
  options={[
    { label: "Frontend", value: "frontend" },
    { label: "Backend", value: "backend" },
    { label: "DevOps", value: "devops" },
    { label: "Mobile", value: "mobile" }
  ]}
/>

MultiSelect States

The component supports different states, such as disabled, read-only, and loading.

Disabled MultiSelect

The disabled state prevents any user interaction with the field and prevents data from being submitted through a form.

tsx

<MultiSelect
  name="disabled-multi"
  label="Disabled selection"
  disabled
  defaultValue={["opt1"]}
  options={[
    { label: "Option 1", value: "opt1" },
    { label: "Option 2", value: "opt2" },
    { label: "Option 3", value: "opt3" },
  ]}
/>

Read-only MultiSelect

The read-only state allows the user to view the field value but cannot edit it. Unlike the disabled state, the value can be selected and copied, and field data can be submitted via a form.

tsx

<MultiSelect
  name="readonly-multi"
  label="Read only"
  readOnly
  defaultValue={["frontend", "backend"]}
  options={[
    { label: "Frontend", value: "frontend" },
    { label: "Backend", value: "backend" },
    { label: "Mobile", value: "mobile" },
    { label: "DevOps", value: "devops" },
  ]}
/>

Loading state

The loading state displays a spinner and automatically disables input. The spinner appears on the left by default, or on the right if there is a rightIcon.

tsx

<MultiSelect
  name="loading-multi"
  label="Loading options..."
  isLoading
  options={[]}
/>

Validation and Errors

The component integrates with form validation systems and can display error messages. If an error message is provided via the errorMessage property, it will take precedence over messages from the form provider.
Customizable Forms
For forms, it is recommended to use the FormProvider which offers native integration with all form tools.

tsx

<MultiSelect
  name="required-multi"
  label="Required Skills"
  showAsterisk
  errorMessage="Select at least one skill"
  leftIcon={Code}
  options={[
    { label: "JavaScript", value: "js" },
    { label: "TypeScript", value: "ts" },
    { label: "React", value: "react" },
    { label: "Vue", value: "vue" },
  ]}
/>

Properties

name - string (required) Name of the field for form manipulation
options - { label: string; value: string }[] (required) Array of options with label and value
id - string Optional unique identifier for the component
value - string[] Controlled value - array of selected values
defaultValue - string[] (default: []) Default values ​​selected for uncontrolled use
showAsterisk - boolean Whether to show an asterisk in the label for required fields
label - string Label text to display above the multiselect
errorMessage - string Error message to display below the multiselect
placeholder - string (default: Select...") Placeholder text when no option is selected
notFoundText - string (default: No options available") Text displayed when no options match the search
className - string Additional CSS classes for styling
disabled - boolean (default: false) If the multiselect is disabled
readOnly - boolean (default: false) If the multiselect is read-only
isLoading - boolean (default: false) Controls the loading state with the spinner
isSearchable - boolean (default: false) Whether the search functionality is supported
closeOnSelect - boolean (default: false) Whether the dropdown should close after selecting an option
onSearch - (value: string) => void Callback function called when the search value changes
onChange - (value: string[]) => void Callback function called when the selected values ​​change
onFocus - () => void Callback function called when the multiselect gains focus
onBlur - (e: FocusEvent<HTMLDivElement>) => void Callback function called when the multiselect loses focus
size - "md" | "lg" (default: "md") Multiselect size
variant - "solid" | "outline" | "underline" (default: "solid") Multiselect visual variant
prefix - string | LucideIcon Text or icon to display at the top of the multiselect
leftIcon - LucideIcon Optional icon to display on the left side
optionMaxHeight - number Maximum height for the options dropdown
Option Format
Options must always follow the format { label: string; value: string }[] where label is the displayed text and value is the internal value used by the form.

Performance

For very large lists (>1000 items), consider:
  • Implement server-side search with onSearch
  • Use pagination or on-demand loading
  • Use virtualization for efficient rendering

Important Notes

  • Options must always have a unique label and value
  • The value is stored and sent to the form as stringified JSON
  • isSearchable enables local search by default; use onSearch for custom search
  • closeOnSelect is useful for occasional single selections
  • Local search is case-insensitive and searches the label text
On this page