ssuggestor v1.0.0
ssuggestor
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.
Demo
Live Demo: carloluis.github.io/ssuggestor
Suggestor example on CodePen
Instalation
# using yarn
yarn add ssuggestor
# using npm
npm i ssuggestor
Usage
npm
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(
<Suggestor
list={['suggestion-a', 'suggestion-b', 'suggestion-c', '...', 'suggestion-z']}
theme={b3Theme}
onChange={value => {}}
onSelect={(value, suggestion) => {}}
placeholder="placeholder text..."
/>,
document.querySelector('#app')
);
browser
Include react
dependencies and ssuggestor
scripts:
<script src="https://unpkg.com/react@16.3.0/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@16.3.0/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/ssuggestor@0.9.0/dist/ssuggestor.min.js"></script>
<!-- bootstrap styles -->
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
Description
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.
Example:
- input pattern:
sugge
- items on suggestion list: autoSuggest, ssüggèstor and suggests
Then,
- 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.
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 <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.
Theme
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 importssuggestor/dist/styles.css
- Bootstrap classes:
input-group
,form-group
anddropdown-menu
.
{
"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.
{
"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.
Focus
Use public method focus
to set focus in <input>
element.
<suggestor-instance>.focus();
Development
In order to run this project locally clone this repo, restore dependencies and execute dev
task:
git clone https://github.com/carloluis/ssuggestor.git
cd ssuggestor
yarn
yarn dev
Open browser on localhost:9000
License
MIT © Carloluis
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago