Usage no npm install needed!

<script type="module">
  import ssuggestor from '';



GitHub license GitHub release Travis branch Coverage Status Codacy Badge npm npm Package Quality PeerDependencies code style: prettier Twitter

React component that enables users to quickly find and select from a pre-populated list of values as they type. Current theme provided use Bootstrap styles.


Live Demo:

Suggestor example on CodePen


# using yarn
yarn add ssuggestor

# using npm
npm i ssuggestor



import React from 'react';
import { render } from 'react-dom';
import 'ssuggestor/dist/styles.css';
import b3Theme from 'ssuggestor/dist/bootstrap-3.json';
import Suggestor from 'ssuggestor';

        list={['suggestion-a', 'suggestion-b', 'suggestion-c', '...', 'suggestion-z']}
        onChange={value => {}}
        onSelect={(value, suggestion) => {}}
        placeholder="placeholder text..."


Include react dependencies and ssuggestor scripts:

<script src=""></script>
<script src=""></script>
<script src=""></script>

<!-- bootstrap styles -->
<link href="">


This Simple Suggestor package provides a React component as default export: It handles clicks outside of DOM component in order to close the suggestion list. All pattern matches are highlighted.


  • input pattern: sugge
  • items on suggestion list: autoSuggest, ssüggèstor and suggests


  • matches are case insensitive: autoSuggest
  • pattern test is performed removing accents: ssüggèstor

Suggestion Objects

Suggestion objects use requires a selector function to convert each object into string representation which will be displayed on the suggestion list.


Prop Type Default Description
accents Boolean false whether to differentiate chars with accents or not
arrow Boolean true ▼ icon - open suggestion list
theme Object {} JSON theme with css classes for each dom element
close Boolean true ✖︎ icon - delete current value
list Array -- suggestions (required)
selector Function s => s suggestions selector (must return a string)
openOnClick Boolean true whether suggestion list opens on click or not
onSelect Function () => {} onSelect handler: (value, suggestion) => { }
onChange Function () => {} onChange handler: (value) => { }
onKey Function () => {} onKey handler: (keyEvent) => { }
placeholder String -- input placeholder text
required Boolean false if true, set required attribute on <input> element
selectOnTab Boolean false if true, enables Tab key to select ssuggestion
style Object -- inline styles for component's root element
suggestOn Number 1 minimum size of search string to show suggestions
tooltip String -- input title text (simple tooltip)
value String '' initial value
useKeys Boolean true whether to use supported keys or not

Supported Keys

Up, Down, Enter, Escape & Tab.


Provide JSON with classes for styling the component:

    "root": "class(es) used on wrapper element",
    "input": "<input> element class(es)",
    "arrow": "open <span> indicator class(es)",
    "close": "remove <span> indicator class(es)",
    "list": "<ul> class(es)",
    "item": "<li> class(es)",
    "activeItem": "active <li> class(es)"

This package also provides a theme using custom classes from styles.css and others from Bootstrap.

  • Custom class names start with the ss- prefix. Required to import ssuggestor/dist/styles.css
  • Bootstrap classes: input-group, form-group and dropdown-menu.
Bootstrap 3 Theme
    "root": "input-group ss-root",
    "input": "form-control ss-input",
    "arrow": "ss-arrow",
    "close": "ss-remove",
    "list": "dropdown-menu ss-list",
    "item": "",
    "activeItem": "ss-over-item"

Note that you need to import the Bootstrap3 theme from ssuggestor/dist/bootstrap-3.json

Check usage on npm section.

Bootstrap 4 Theme
    "root": "input-group ss-root",
    "input": "form-control ss-input",
    "arrow": "ss-arrow",
    "close": "ss-remove",
    "list": "dropdown-menu ss-list",
    "item": "dropdown-item",
    "activeItem": "ss-over-item"

Note that you need to import the Bootstrap4 theme from ssuggestor/dist/bootstrap-4.json

Check usage on npm section.


Use public method focus to set focus in <input> element.



In order to run this project locally clone this repo, restore dependencies and execute dev task:

git clone
cd ssuggestor
yarn dev

Open browser on localhost:9000


MIT © Carloluis