https://github.com/carloluis/ssuggestor
react-simple-suggestor: search with suggestions
https://github.com/carloluis/ssuggestor
autocomplete autocomplete-search bootstrap component react react16 suggestor
Last synced: 8 days ago
JSON representation
react-simple-suggestor: search with suggestions
- Host: GitHub
- URL: https://github.com/carloluis/ssuggestor
- Owner: carloluis
- License: mit
- Created: 2017-01-24T19:09:23.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T19:06:06.000Z (about 3 years ago)
- Last Synced: 2025-10-06T16:00:57.185Z (4 months ago)
- Topics: autocomplete, autocomplete-search, bootstrap, component, react, react16, suggestor
- Language: JavaScript
- Homepage: https://carloluis.github.io/ssuggestor/
- Size: 2.8 MB
- Stars: 19
- Watchers: 1
- Forks: 4
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ssuggestor
[](./LICENSE)
[](https://github.com/carloluis/ssuggestor/releases)
[](https://travis-ci.org/carloluis/ssuggestor)
[](https://coveralls.io/github/carloluis/ssuggestor)
[](https://www.codacy.com/app/carloluis/ssuggestor?utm_source=github.com&utm_medium=referral&utm_content=carloluis/ssuggestor&utm_campaign=badger)
[](https://www.npmjs.com/package/ssuggestor)
[](https://npm-stat.com/charts.html?package=ssuggestor)
[](http://packagequality.com/#?package=ssuggestor)
[](https://david-dm.org/carloluis/ssuggestor?type=peer)
[](https://github.com/prettier/prettier)
[](https://twitter.com/intent/tweet?text=check%20out%20this%20simple%20suggestor%20component%20on&url=https%3A%2F%2Ft.co%2FpjuWm9EaCa&hashtags=react16,ssuggestor)
> React component that enables users to quickly find and select from a pre-populated list of values as they type.
> Current themes provided use [Bootstrap](http://getbootstrap.com/) and custom styles.
## Demo
Live Demo: [carloluis.github.io/ssuggestor](https://carloluis.github.io/ssuggestor/)
## Instalation
```bash
# using yarn
yarn add ssuggestor
# using npm
npm i ssuggestor
```
## Usage
Include `react` dependencies and `ssuggestor` script. Also include `ssuggestor` styles and theme if required.
### npm
```jsx
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';
render(
{}}
onSelect={(value, suggestion) => {}}
placeholder="placeholder text..."
/>,
document.querySelector('#app')
);
```
### browser
```html
```
Check suggestor example on [CodePen](http://codepen.io/carloluis/pen/rjpLYw/).
## Description
Simple Suggestor package provides a React component as default export.
Clicks outside of DOM component are tracked in order to close the suggestion list.
Pattern matches are highlighted in bold.
Example:
* input pattern: `sugge`
* items on suggestion list: _autoSuggest_, _ssüggèstor_ and _suggests_
Then,
* matches are case insensitive: _auto**Sugge**st_
* pattern test is performed removing accents: _s**süggè**stor_
### Suggestion Objects
The usage of suggestion objects requires a `selector` function to convert each object into string representation which will be displayed on the suggestion list.
### Props:
| 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 `` 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](#supported-keys) or not |
#### Supported Keys
Up, Down, Enter, Escape & Tab.
#### Theme
Provide `JSON` with classes for styling the component:
```json
{
"root": "class(es) used on wrapper element",
"input": " element class(es)",
"arrow": "open indicator class(es)",
"close": "remove indicator class(es)",
"list": " class(es)",
"item": "- class(es)",
"activeItem": "active
- 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
```json
{
"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](#npm) section.
Bootstrap 4 Theme
```json
{
"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](#npm) section.
### Focus
Use public method `focus` to set focus in `` element.
```js
.focus();
```
## Development
In order to run locally: first clone the [git repo](https://github.com/carloluis/ssuggestor.git), then restore dependencies and execute the `dev` task:
```bash
git clone https://github.com/carloluis/ssuggestor.git
cd ssuggestor
yarn
yarn dev
```
Open browser on [localhost:9000](http://localhost:9000/)
## License
MIT © [Carloluis](https://github.com/carloluis)