Home

Awesome

NPM npm downloads Issues License style: styled-components

react-functional-select

Micro-sized & micro-optimized select component for React.js

See the accompanying Interactive Storybook UI Site for live demos and detailed docs.

<strong>Key features:</strong>

<strong>Peer dependencies:</strong>

Overview

Essentially, this is a focused subset of react-select's API that is engineered for ultimate performance and minimal bundle size. It is built entirely with the React Hooks API (no legacy class components). The primary design principal revolves around weighing the cost/benefits of adding a feature against the impact to performance and/or number of lines of code its addition would have.

Any expected features not in the current API is likely due to the reason that such features would have added significant overhead to the package. In addition, if we expose the right public methods and/or callback properties, this feature should be trivial to add to wrapping components - proper decoupling and abstraction of code is key to keeping such channels open for similar customizations that can be kept out of this package. Please, feel free to offer enhancement ideas with/without technical solutions.

Installation

$ npm i react-window styled-components react-functional-select
$ yarn add react-window styled-components react-functional-select

<strong><em>Note that you need to be on a react version that supports hooks (>= 16.8.6)</em></strong>

Usage

import { Select } from 'react-functional-select';
import React, { useState, useEffect, useCallback, type ComponentProps } from 'react';
import { Card, CardHeader, CardBody, Container, SelectContainer } from '../shared/components';

type SelectProps = ComponentProps<typeof Select>;

type Option = Readonly<{
  id: number;
  city: string;
  state: string;
}>;

const CITY_OPTIONS: Option[] = [
  { id: 1, city: 'Austin', state: 'TX' },
  { id: 2, city: 'Denver', state: 'CO' },
  { id: 3, city: 'Chicago', state: 'IL' },
  { id: 4, city: 'Phoenix', state: 'AZ' },
  { id: 5, city: 'Houston', state: 'TX' }
];

const SingleSelect: React.FC<SelectProps> = ({ isDisabled }) => {
  const [isInvalid, setIsInvalid] = useState<boolean>(false);
  const [selectedOption, setSelectedOption] = useState<Option | null>(null);

  const getOptionValue = useCallback((opt: Option): number => opt.id, []);
  const onOptionChange = useCallback((opt: Option | null): void => setSelectedOption(opt), []);
  const getOptionLabel = useCallback((opt: Option): string => `${opt.city}, ${opt.state}`, []);

  useEffect(() => {
    if (isDisabled) {
      setIsInvalid(false);
    }
  }, [isDisabled]);

  return (
    <Container>
      <Card>
        <CardHeader>
          {`Selected Option: ${JSON.stringify(selectedOption || {})}`}
        </CardHeader>
        <CardBody>
          <SelectContainer>
            <Select
              isClearable
              isInvalid={isInvalid}
              options={CITY_OPTIONS}
              isDisabled={isDisabled}
              onOptionChange={onOptionChange}
              getOptionValue={getOptionValue}
              getOptionLabel={getOptionLabel}
            />
          </SelectContainer>
        </CardBody>
      </Card>
    </Container>
  );
};

export default SingleSelect;

Properties

All properties are technically optional (with a few having default values). Very similar to react-select's API.

<strong><em>Note that the following non-primitive properties should be properly memoized if defined:</em></strong><br>clearIcon, caretIcon, options, renderOptionLabel, onMenuOpen, onOptionChange, onKeyDown, getOptionLabel, getOptionLabel, getOptionValue, onInputBlur, onInputFocus, onInputChange, onSearchChange, getIsOptionDisabled, getFilterOptionString, themeConfig

PropertyTypeDefaultDescription
inputIdstringundefinedThe id of the autosize search input control
selectIdstringundefinedThe id of the parent select container element
menuIdstringundefinedThe id of the menu container element
ariaLabelstringundefinedAria label (for assistive tech)
isMultiboolfalseDoes the control allow for multiple selections (defaults to single-value mode)
asyncboolfalseIs the component in 'async' mode - when in 'async' mode, updates to the input search value will NOT cause the effect useMenuOptions to execute (this effect parses options into stateful value menuOptions)
autoFocusboolfalseFocus the control following initial mount of component
lazyLoadMenuboolfalseIf true, the menu (wrapper & virtualized list components) will rendered in DOM only when menuOpen state is true
isLoadingboolfalseIs the select in a state of loading - shows loading dots animation
isInvalidboolfalseIs the current value invalid - control recieves invalid styling
inputDelaynumberundefinedThe debounce delay in for the input search (milliseconds)
pageSizenumber5Number of options to jump in menu when page{up
isDisabledboolfalseIs the select control disabled - recieves disabled styling
requiredboolfalseIs the select control required - applied to the input element. When true, the optionally specified CSS from the themeConfig.input.cssRequired field will be applied to the input element.
placeholderstringSelect option..Placeholder text for the select value
menuWidthstringnumber100%
menuItemSizenumber35The height of each option in the menu (px)
isClearableboolfalseIs the select value clearable
noOptionsMsgstringNo optionsThe text displayed in the menu when there are no options available (to hide menu when search returns no items, set to null or '')
loadingMsgstringLoading..The text displayed in the menu when isLoading === true
clearIconReactNode OR ((state: any) => ReactNode)undefinedCustom clear icon node - state forwarded to a function is { menuOpen, isLoading, isInvalid, isDisabled }
caretIconReactNode OR ((state: any) => ReactNode)undefinedCustom caret icon node - state forwarded to a function is { menuOpen, isLoading, isInvalid, isDisabled }
loadingNodeReactNodeundefinedCustom loading node
optionsarray[]The menu options
isSearchablebooltrueWhether to enable search functionality or not
hideSelectedOptionsboolfalseHide the selected option from the menu (if undefined and isMulti = true, then defaults to true)
openMenuOnClickbooltrueIf true, the menu can be toggled by clicking anywhere on the select control; if false, the menu can only be toggled by clicking the 'caret' icon on the far right of the control
menuMaxHeightnumber300Max height of the menu element - this effects how many options react-window will render
menuOverscanCountnumber1correlates to react-window property overscanCount: The number of items (options) to render outside of the visible area. Increasing the number can impact performance, but is useful if the option label is complex and the renderOptionLabel prop is defined
itemKeySelectorstringnumberundefined
menuScrollDurationnumber300Duration of scroll menu into view animation
menuItemDirection'ltr' OR 'rtl''ltr'The direction of text for each menu option and position of the menu's scroll bar (react-window's direction prop)
ariaLabelledBystringundefinedHTML ID of an element that should be used as the label (for assistive tech)
ariaLive'off' OR 'polite' OR 'assertive''polite'Used to set the priority with which screen reader should treat updates to live regions (translates to aria-live attribute)
openMenuOnFocusboolfalseOpen the menu when the select control recieves focus
initialValueanyundefinedInitial select value
tabSelectsOptionbooltrueSelect the currently focused option when the user presses tab
blurInputOnSelectboolfalseRemove focus from the input when the user selects an option (useful for dismissing the keyboard on touch devices)
closeMenuOnSelectbooltrueClose the select menu when the user selects an option
isAriaLiveEnabledboolfalseEnables visually hidden div that reports stateful information (for assistive tech)
scrollMenuIntoViewbooltruePerforms animated scroll to show menu in view when menu is opened (if there is room to do so)
backspaceClearsValuebooltrueRemove the currently focused option when the user presses backspace
filterMatchFrom'any' OR 'start''any'Position in stringified option to match search input
menuPosition'top' OR 'auto' OR 'bottom''bottom'Determines where menu will be placed in relation to the control - 'auto' will first check if menu has space to open below the control, otherwise it will open above the control.
filterIgnoreCasebooltrueSearch input ignores case of characters when comparing
filterIgnoreAccentsboolfalseSearch input will strip diacritics from string before comparing
onMenuOpen(...args: any[]) => voidundefinedCallback function executed after the menu is opened
onMenuClose(...args: any[]) => voidundefinedCallback function executed after the menu is closed
onOptionChange(data: any) => voidundefinedCallback function executed after a new option is selected
onKeyDown(e: KeyboardEvent, input?: string, focusedOption?: FocusedOption) => voidundefinedCallback function executed onKeyDown event
getOptionLabel(data: any) => stringnumberundefined
getOptionValue(data: any) => stringnumberundefined
onInputBlur(e: FocusEvent) => voidundefinedHandle blur events on the search input
onInputFocus(e: FocusEvent) => voidundefinedHandle focus events on the search input
onInputChange(value: string) => voidundefinedHandle change events on the search input
onSearchChange(value: string) => voidundefinedCallback executed after the debounced search input value is persisted to the component's state - if no debounce is defined via the inputDelay property, it probably makes more sense to use onInputChange instead.
renderOptionLabel(data: any) => ReactNodeundefinedFormats option labels in the menu and control as JSX.Elements or React Components (by default will use getOptionLabel)
renderMultiOptions(params: any) => ReactNodeundefinedAllows for customization as to how multi-select options should be formatted. The MultiParams contains the array of selected options `{ selected: Array<{ data: any, value: string
getIsOptionDisabled(data: any) => booleanundefinedWhen defined will evaluate each option to determine whether it is disabled or not (if not specified, each option will be evaluated as to whether or not it contains a property of isDisabled with a value of true)
getFilterOptionString(option: any) => stringundefinedWhen defined will take each option and generate a string used in the filtering process (by default, will use option.label)
themeConfigPartial<DefaultTheme>undefinedObject that takes specified property key-value pairs and merges them into the theme object
menuPortalTargetElementundefinedWhether the menu should use a portal, and where it should attach
memoOptionsboolfalseWhether to memoize each Option component

Inspiration

This project was inspired by react-select.

License

MIT licensed. Copyright (c) Matt Areddia 2022.