Home

Awesome

⚠️ Looking for maintainers

First of all, I want to thank you all for the amazing support over the years. This was one of my first open source projects and also my first successful one. I am beyond grateful for all the 33! contributors, wouldn't have been possible to run this project without you.

A lot happened last year. I had my first born son, I had a few time consuming freelance gigs and a few startups that grew. This took time away from open source and I feel I can't do this component justice anymore. Not by myself at least.

I still believe in a tiny, super fast and zero-dependency select component. If there's anyone out there that wants to co-maintain this with me, please reach out to discuss the next steps. Send me an email at hola@tobiasbleckert.se or hit me up on Twitter

<p align="center"> <img src="https://user-images.githubusercontent.com/263465/175054036-90835869-74dc-40f1-a541-adea18da9b8f.png" alt="React Select Search" /> </p> <h6 align="center"> <a href="https://react-select-search.com">Demo</a> · <a href="https://github.com/tbleckert/react-select-search#quick-start">Quick start</a> · <a href="https://github.com/tbleckert/react-select-search#config">Config</a> · <a href="https://github.com/tbleckert/react-select-search#headless-mode-with-hooks">Headless</a> </h6> <p align="center"> <a href='https://coveralls.io/github/tbleckert/react-select-search'> <img src='https://img.shields.io/coveralls/github/tbleckert/react-select-search?style=for-the-badge' alt='Coverage Status' /> </a> <a href="https://www.npmjs.com/package/react-select-search"> <img src="https://img.shields.io/npm/dm/react-select-search.svg?style=for-the-badge" style="max-width:100%;" /> </a> <a href="https://bundlephobia.com/result?p=react-select-search"> <img src="https://img.shields.io/bundlephobia/minzip/react-select-search?style=for-the-badge" /> </a> <a href="#contributors"> <img src="https://img.shields.io/github/contributors/tbleckert/react-select-search?style=for-the-badge" /> </a> </p>

Features

Install

Install it with npm (npm i react-select-search) or yarn (yarn add react-select-search) and import it like you normally would.

Quick start

import SelectSearch from 'react-select-search';

/**
 * The options array should contain objects.
 * Required keys are "name" and "value" but you can have and use any number of key/value pairs.
 */
const options = [
    {name: 'Swedish', value: 'sv'},
    {name: 'English', value: 'en'},
    {
        type: 'group',
        name: 'Group name',
        items: [
            {name: 'Spanish', value: 'es'},
        ]
    },
];

/* Simple example */
<SelectSearch options={options} value="sv" name="language" placeholder="Choose your language" />

For more examples, you can take a look in the stories directory.

You will also need some CSS to make it look right. Example theme can be found in style.css. You can also import it:

import 'react-select-search/style.css'

Use with SSR

For use with SSR you might need to use the commonjs bundle (react-select-search/dist/cjs). If you want to utilise the example theme (style.css) you need to check if your build script manipulates class names, for example minifies them. If that's the case, you can use CSS modules to get the class names from the style.css file and apply them using the className object. Example can be seen here as well as here https://react-select-search.com/?path=/story/custom--css-modules.

Headless mode with hooks

If you want complete control (more than styling and custom renderers) you can use hooks to pass data to your own components and build it yourself.

import React from 'react';
import { useSelect } from 'react-select-search';

const CustomSelect = ({ options, value, multiple, disabled }) => {
    const [snapshot, valueProps, optionProps] = useSelect({
        options,
        value,
        multiple,
        disabled,
    });

    return (
        <div>
            <button {...valueProps}>{snapshot.displayValue}</button>
            {snapshot.focus && (
                <ul>
                    {snapshot.options.map((option) => (
                        <li key={option.value}>
                            <button {...optionProps} value={option.value}>{option.name}</button>
                        </li>
                    ))}
                </ul>
            )}
        </div>
    );
};

Configuration

Below is all the available options you can pass to the component. Options without defaults are required.

NameTypeDefaultDescription
optionsarraySee the options documentation below
getOptionsfunctionnullGet options through a function call, can return a promise for async usage. See get options for more.
filterOptionsarraynullAn array of functions that takes the last filtered options and a search query if any. Runs after getOptions.
valuestring, arraynullThe value should be an array if multiple mode.
multiplebooleanfalseSet to true if you want to allow multiple selected options.
searchbooleanfalseSet to true to enable search functionality
disabledbooleanfalseDisables all functionality
closeOnSelectbooleantrueThe selectbox will blur by default when selecting an option. Set this to false to prevent this behavior.
debouncenumber0Number of ms to wait until calling get options when searching.
placeholderstringempty stringDisplayed if no option is selected and/or when search field is focused with empty value.
idstringnullHTML ID on the top level element.
autoCompletestring, on/offoffDisables/Enables autoComplete functionality in search field.
autoFocusbooleanfalseAutofocus on select
classNamestring, objectselect-search-boxSet a base class string or pass a function for complete control. Se custom classNames for more.
renderOptionfunctionnullFunction that renders the options. See custom renderers for more.
renderGroupHeaderfunctionnullFunction that renders the group header. See custom renderers for more.
renderValuefunctionnullFunction that renders the value/search field. See custom renderers for more.
emptyMessageReact nodenullSet empty message for empty options list, you can provide render function without arguments instead plain string message
onChangefunctionnullFunction to receive and handle value changes.
onFocusfunctionnullFocus callback.
onBlurfunctionnullBlur callback.

The options object

The options object can contain any properties and values you like. The only required one is name.

PropertyTypeDescriptionRequired
namestringThe name of the optionYes
valuestringThe value of the optionYes, if the type is not "group"
typestringIf you set the type to "group" you can add an array of options that will be groupedNo
itemsarrayArray of option objects that will be used if the type is set to "group"Yes, if type is set to "group"
disabledbooleanSet to true to disable this optionNo

Custom class names

If you set a string as the className attribute value, the component will use that as a base for all elements. If you want to fully control the class names you can pass an object with classnames. The following keys exists:

Custom renderers

If CSS isn't enough, you can also control the HTML for the different parts of the component.

CallbackArgsDescription
renderOptionoptionsProps: object, optionData: object, optionSnapshot: object, className: stringControls the rendering of the options.
renderGroupHeadername: stringControls the rendering of the group header name
renderValuevalueProps: object, snapshot: object, className: stringControls the rendering of the value/input element

The optionProps and the valueProps are needed for the component you render to work. For example:

<SelectSearch renderValue={(valueProps) => <input {...valueProps} />} />

Monkeypatch it if you need to but make sure to not remove important props.

The optionSnapshot is an object that contains the object state: { selected: bool, highlighted: bool }.

Get options

You can fetch options asynchronously with the getOptions property. You can either return options directly or through a Promise.

function getOptions(query) {
    return new Promise((resolve, reject) => {
        fetch(`https://www.thecocktaildb.com/api/json/v1/1/search.php?s=${query}`)
            .then(response => response.json())
            .then(({ drinks }) => {
                resolve(drinks.map(({ idDrink, strDrink }) => ({ value: idDrink, name: strDrink })))
            })
            .catch(reject);
    });
}

The function runs on each search query update, so you might want to throttle the fetches. If you return a promise, the class is-loading will be applied to the main element, giving you a chance to change the appearance, like adding a spinner. The property fetching is also available in the snapshot that is sent to your render callbacks.

Contributors

<a href="https://github.com/tbleckert/react-select-search/graphs/contributors"> <img src="https://contrib.rocks/image?repo=tbleckert/react-select-search" /> </a>

Made with contrib.rocks.