mutli-select-example v1.0.0

MultiSelect

MultiSelect is a select component that can lookup or match text as a user types. MultiSelect will search across multiple sources and show matches in a dropdown list. It is intended to be an alternative to having multiple select components, and supports and/or opertions and multiple comparison types.

To install

yarn add multi-select

or

npm i multi-select

Quick start

const dataSource: DataSource[] = [
  {
    name: 'list',
    title: 'list of strings',
    comparisons: defaultComparison,
    precedence: 1,
    source: ['asdas', 'assda', 'loadsp'],
  },
  {
    name: 'promise',
    title: 'Promise list',
    comparisons: defaultComparison,
    precedence: 3,
    source: async (text) => {
      return new Promise((resolve) => {
        setTimeout(
          () =>
            resolve(
              ['delayed', 'aploked', 'loadsp'].filter((item) =>
                item.includes(text),
              ),
            ),
          250,
        )
      })
    },
  },
  {
    name: 'function',
    title: 'Functions',
    comparisons: numberComparisons,
    match: (text: string) => !isNaN(Number(text)),
    value: (text: string) => Number.parseInt(text),
  },
  {
    name: 'regex',
    title: 'Regular Expression',
    comparisons: stringComparisons,
    precedence: 2,
    match: /^[a-zA-Z]{2,}$/,
    value: (text: string) => text,
  },
]

const App = () => {
  const [matchers, setMatchers] = React.useState<Matcher[]>()

  return (
    <>
      <h2>MutliSelect</h2>
      <MutliSelect
        matchers={matchers}
        dataSources={dataSource}
        onMatchersChanged={setMatchers}
      />
  )
}  

Properties

• matchers - matchers to show in the control
• dataSources - datasources available to the control
• defaultItemLimit - default number of items to show for each datasource in the dropdown
• simpleOperation - only allow users to selct comparisons, no brackets or and or
• onMatchersChanged - event for when the matchers change
• clearIcon - alternative icon to the X
• maxDropDownHeight - the maximium hieght of the options dropdown
• minDropDownWidth - the minimum width of the option dropdown
• searchStartLength - the length of text at which to look for matches
• styles - allows styles to be set for the different components

DataSources

There are two types of dataSource a lookup source that can be either a list or a promise, and a match datasource that can be either a function or a regex.

Lookup

source: SourceItem[] | ((text: string) => Promise<SourceItem[]>)
textGetter?: (item: object) => string
valueGetter?: (item: object) => Value
ignoreCase?: boolean
itemLimit?: number
searchStartLength?: number

• Source - either a list of strings/objects, or a promise that returns a list of strings/objects
• textGetter - if the source is an object, then this is a function to extract the display texst
• valueGetter - if the source is an object, then this is a function to extract the value
• ignoreCase - a boolean value to indicate if case is ignored when matching items
• itemLimit - the maximium number of matches to shouw ina dropdown
• searchStartLength - the text length required before datas source is searched

Match

match: RegExp | ((text: string) => boolean)
value: (text: string) => Value

• match - either a regex or a function, to determine if the text entered is a match
• value - a function that can extract a value from the text

Operators and Comparisons

and & the compairsons on both sides must be true
or |  the comparisons on either side can be true

=   value must equal the matcher
!   value must not equal the matcher
>   value must be greater than the matcher
<   value must be less than the matcher
>=  value must be equal to or greater than the matcher
<=  value must equal to or less than the matcher
*   value must be like the matcher
!*  value must not be like the matcher
<*  value starts with
>*  value ends with

(   open bracket
)   close bracket

Keyboard shortcuts

• Shift + ArrowLeft - navigate through the matchers
• Shift + ArrowRight - navigate through the matchers
• Ctrl + ArrowLeft - move selected matcher left
• Ctrl + ArrowRight - move selected matcher right
• Shift + Backspace - delete previous matcher
• Ctrl + Backspace - delete all matchers
• ArrowUp - move to next option in the list
• ArrowDown - move to previuos option in the list
• PageUp - move to next data source group in the option list
• PageDown - move to previous data source group in the option list
• Home - move to first data source group in the option list
• End - move to last data source group in the option list
• Enter - select current option
• Tab - select current option

Styling

The following components can be styled

• optionsList
• option
• optionCategory
• matcherView
• matcherViewSelected
• atcherToolTip
• matcherEdit
• input
• mutliSelect
• errorMessage

Style structure

{
  optionsList?: React.CSSProperties
  option?: React.CSSProperties
  optionCategory?: React.CSSProperties
  matcherView?: React.CSSProperties
  matcherViewSelected?: React.CSSProperties
  matcherToolTip?: React.CSSProperties
  matcherEdit?: React.CSSProperties
  input?: React.CSSProperties
  mutliSelect?: React.CSSProperties
  errorMessage?: React.CSSProperties
}

Global Variables

MultiSelect Main

• border - --multiSelectMainBorder, default=1px solid rgb(204, 204, 204)
• background color - --multiSelectMainBackgroundColor, default=rgb(255, 255, 255)
• clear icon color - --multiSelectClearIcon
• clear icon hover color - --multiSelectClearIconHoverColor, default=gray

Matcher View

• background-color - --matcherViewMainBackgroundColor
• delete icon color - --matcherViewMainDeleteIconColor
• delete icon hover - --matcherViewMainDeleteIconHowverColor - default=gray
• warning background color - --matcherViewWarningBackgroundColor, default=orange

ToolTip

• background-color - --matcherViewTooltipBackgroundColor, default=rgb(255, 255, 255)
• border - --matcherEditOptionsBorder, default=1px solid rgb(204, 204, 204)

Error Message

• background-color - --errorMessageMainBackgroundColor, default=rgb(255, 255, 255)
• border - --matcherEditOptionsBorder, default=1px solid rgb(204, 204, 204)
• color --errorMessageMainErrorColor, default=red
• icon hover color - --errorMessageMainErrorHoverColor, default=rgb(255, 124, 124)

Option List

• color - --matcherEditOptionsColor, default=black
• border - --matcherEditOptionsBorder, default=1px solid rgb(204, 204, 204)
• background-color - --matcherEditOptionsBackgroundColor, default=rgb(255, 255, 255)
• active opton background - --optionListActiveOption, default=lightgray
• option category background - --matcherEditMainCategoryBackground, defalt=darkgrey