artof-select

A simple, but powerful React Select component. Can be used for both Select Single React form element and Select Multiple React form element.

Key features:

• Based on native HTMLSelectElement props and methods
• Supports multiple selection
• Supports searching through options list
• Fully customisable design
• Select provides display of hints and error notifications
• Multiple selected options can be shown as [tag] [tag] [tag]
• Supports native keyboard events, like Tab, Arrow Up | Down to navigate over the dropdown options and Enter (or even Spacebar) to apply selected option(s).
• Supports custom React.ReactNode component as option element

In addition, this component works with react-popper to make better dropdown positioning.

Demo Storybook here

Installation and usage

npm i artof-select

or

yarn add artof-select

As soon as it installed, you can easily use Select in your app:

import React from 'react';
import { Select } from 'artof-select';

// custom
import 'artof-select/dist/index.scss';

const App = () => {
  const [value, setValue] = useState();

  const handleChange = (event) => {
    setValue(event.currentTarget.value);
  }

  return (
    <Select
      label="Some label"
      value={value}
      options={[]}
      onChange={handleChange}
      allowSearch={true}
    />
  )
}

Props

Common props you may want to specify include:

Props	Default	Description
allowClearAll	false	Add button to clear the selection
allowMarkWords	true	Wrap keywords with <mark /> for allowSearch={true}
allowRemoveTag	false	Add additional close icon for every tag, when asTags={true}
allowSearch	false	Allow the user to search for inside options
allowSelectAll	false	Include Select All button with multiple options
allowTagsCount	false	Add counter before selected tags, when asTags={true}
aria-expanded	false	If true - can open the Dropdown on init
asTags	false	Use with multiple={true} to display selections as tags
autoFocus	undefined	Default <select />'s attribute. Set focus when did mount
className	undefined	Additional className can be attached to the wrapper
datatype	undefined	Possibility to pass data-types attributes to <select/>
disabled	undefined	Default <select />'s attribute
dropdownOffset	[0, 4]	Offset dropdown positioning by x and y coordinates
dropdownPosition	bottom-start	Position for Dropdown, based on react-popper props
errorText	undefined	A text below the Select connected with classNames
form	undefined	Default <select />'s attribute
hintText	undefined	A text below the Select (and under the errorText)
id	undefined	Default <select />'s attribute
label	undefined	Generates an label with this name above the Select
labelPosition	before	Position for Label (before
multiple	false	Allow the user to select multiple values
name	undefined	Default <select />'s attribute
onBlur	undefined	Handle the Blur event
onFocus	undefined	Handle the Focus event
onKeyDown	undefined	Handle the KeyDown event
onKeyUp	undefined	Handle the KeyUp event
onToggle	undefined	To handle th Dropdown open\close state
options	[]	Specify the options the user can select from
placeholder	undefined	The text displayed when no option is selected
renderValue	undefined	A function, that can render custom selected value
required	undefined	Default <select />'s attribute
splitterBefore	0	To set additional HTMLDivElement before an option item
style	undefined	Default <select />'s attribute
textSelectAll	Select all	A translation text Select All if allowSelectAll={true}
textSelected	Selected	A translation text Selected %n if multiple={true}
value	undefined	Current value. A string or an string[] if multiple={true}

Also, the onChange prop can return event: React.ChangeEvent<HTMLSelectElement> or values: string[] depend on multiple option.

In addition to above props, you can get access to the Select component with ref. This will allow you to force some events, like: selectRef.current?.focus()

Run the Demo from local

You can check out the demo:

git clone https://github.com/o-mega/artof-select.git
cd artof-select
npm install
npm run dev

This commands should run the Storybook with designed examples at http://localhost:6006

License

MIT Licensed. Copyright (c) Oleg Frolov 2021.