artof-select

The <Select /> component for React

Usage no npm install needed!

<script type="module">
  import artofSelect from 'https://cdn.skypack.dev/artof-select';
</script>

README

artof-select

NPM BUNDLEPHOBIA NPM

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.