react-dropdown-select

Customisable dropdown select for react

Features

• configurable via props
• total custom components overrides for all internals via render prop callbacks (with access to internal props, state and methods)
• stylable via css (or custom components)
• portal support for rendering dropdown outside local DOM tree. e.g. in document.body
• auto position
• small bundle size

Installation

npm install --save react-dropdown-select

Web site

Web site, docs and demo

Motivation

react-select is very nice, but sometimes project requirements are beyond it's abilities

Usage

import:

import Select from "react-dropdown-select";

and use as:

const options = [
  {
    value: 1,
    label: 'Leanne Graham'
  },
  {
    value: 2,
    label: 'Ervin Howell'
  }
];

<Select options={options} onChange={(values) => this.setValues(values)} />;

If your options don't have value and label fields, include labelField and valueField in the props:

const options = [
  {
    id: 1,
    name: 'Leanne Graham'
  },
  {
    id: 2,
    name: 'Ervin Howell'
  }
];

<Select
  options={options}
  labelField="name"
  valueField="id"
  onChange={(values) => this.setValues(values)}
/>;

options and onChange are the minimum required props

Help and Contributions

How to help/contribute

• fix issues, pull request are very welcome
• write, improve docs
• write tests (we use jest)
• suggest features and improvements

Demo

API

Component props

| Prop | Type | Default | Description | | ------------------------------------------------------------------------------------------- | ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | values | array | [] | Selected values | | options | array | [] | Available options, (option with key disabled: true will be disabled) | | keepOpen | bool | false | If true, dropdown will always stay open (good for debugging) | | defaultMenuIsOpen | bool | false | If true, dropdown will be open by default | | autoFocus | bool | false | If true, and searchable, dropdown will auto focus | | clearOnBlur | bool | true | If true, and searchable, search value will be cleared on blur | | clearOnSelect | bool | true | If true, and searchable, search value will be cleared upon value select/de-select | | name | string | null | If set, input type hidden would be added in the component with the value of the name prop as name and select's values as value | | required | bool | false | If set, input type hidden would be added in the component with required prop as true/false | | pattern | string | null | If set, input type hidden would be added in the component with pattern prop as regex | | dropdownGap | number | 5 | Gap between select element and dropdown | | multi | bool | false | If true - will act as multi-select, if false - only one option will be selected at the time | | placeholder | string | "Select..." | Placeholder shown where there are no selected values | | addPlaceholder | string | "" | Secondary placeholder on search field if any value selected | | disabled | bool | false | Disable select and all interactions | | style | object | {} | Style object to pass to select | | className | string | | CSS class attribute to pass to select | | loading | bool | false | Loading indicator | | clearable | bool | false | Clear all indicator | | searchable | bool | true | If true, select will have search input text | | separator | bool | false | Separator line between close all and dropdown handle | | dropdownHandle | bool | true | Dropdown handle to open/close dropdown | | dropdownHeight | string | "300px" | Minimum height of a dropdown | | direction | string | "ltr" | direction of a dropdown "ltr", "rtl" or "auto" | | searchBy | string | label | Search by object property in values | | sortBy | string | null | Sort by object property in values | | labelField | string | "label" | Field in data to use for label | | valueField | string | "value" | Field in data to use for value | | color | string | "#0074D9" | Base color to use in component, also can be overwritten via CSS | | closeOnScroll | bool | false | If true, scrolling the page will close the dropdown | | closeOnSelect | bool | false | If true, selecting option will close the dropdown | | closeOnClickInput | bool | false | If true, clicking input will close the dropdown if you are not searching. | | dropdownPosition | string | "bottom" | Available options are "auto", "top" and "bottom" defaults to "bottom". Auto will adjust itself according Select's position on the page | | keepSelectedInList | bool | true | If false, selected item will not appear in a list | | portal | DOM element | false | If valid dom element specified - dropdown will break out to render inside the specified element | | create | bool | false | If true, select will create value from search string and fire onCreateNew callback prop | | backspaceDelete | bool | true | If true, backspace key will delete last value | | createNewLabel | string | "add {search}" | If create set to true, this will be the label of the "add new" component. {search} will be replaced by search value | | disabledLabel | string | "disabled" | Label shown on disabled field (after) the text | | selectAll | bool | false | Allow to select all | | selectAllLabel | string | "Select all" | Label for "Select all" | | clearAllLabel | string | "Clear all" | Label for "Clear all" | | additionalProps | object | null | Additional props to pass to Select |

Callback props

by using renderer props to override components some of the functionality will have to be handled manually with a help of internal props, states and methods exposed

| Prop | Type | Default | Description | | -------------------------------------------------------------------------------------------------------- | ---- | --------- | -------------------------------------------------------------------------------------- | | onChange | func | | On values change callback, returns array of values objects | | onDropdownClose | func | | Fires upon dropdown close | | onDropdownOpen | func | | Fires upon dropdown open | | onCreateNew | func | | Fires upon creation of new item if create prop set to true | | onClearAll | func | | Fires upon clearing all values (via custom renderers) | | onSelectAll | func | | Fires upon selecting all values (via custom renderers) | | onDropdownCloseRequest | func | undefined | Fires upon dropdown closing state, stops the closing and provides own method close() | | contentRenderer | func | | Overrides internal content component (the contents of the select component) | | itemRenderer | func | | Overrides internal item in a dropdown | | noDataRenderer | func | | Overrides internal "no data" (shown where search has no results) | | optionRenderer | func | | Overrides internal option (the pillow with an "x") on the select content | | inputRenderer | func | | Overrides internal input text | | loadingRenderer | func | | Overrides internal loading | | clearRenderer | func | | Overrides internal clear button | | separatorRenderer | func | | Overrides internal separator | | dropdownRenderer | func | | Overrides internal dropdown component | | dropdownHandleRenderer | func | | Overrides internal dropdown handle | | searchFn | func | undefined | Overrides internal search function | | handleKeyDownFn | func | undefined | Overrides internal keyDown function |

License

MIT