Skip to content

goto-bus-stop/react-abstract-autocomplete

Repository files navigation

react-abstract-autocomplete

This component isn't very accessible and the API predates hooks, which makes it a bit awkward in modern React. I recommend building your own autocomplete on top of something like downshift instead.

Bring-Your-Own-UI autocomplete component for React.

Examples - Examples source code - Installation - Usage - License

Installation

npm install --save react-abstract-autocomplete

Usage

import AutoComplete, { Completion } from 'react-abstract-autocomplete';

const users = [];
const chatCommands = [];

<AutoComplete inputComponent="input">
  <Completion trigger="@" completions={users} minLength={1} />
  <Completion trigger="/" completions={chatCommands} minLength={1} />
</AutoComplete>

For full usage examples, check out the Examples page, and the projects in the examples/ directory.

AutoComplete

Name Type Default Description
inputComponent one of:
 string
 function
'input' Component to use for rendering the input element. Uses native <input /> by default.
The component should accept value, onChange and onKeyDown props.
inputProps object { type: 'text',} Props to pass to the input component.
renderSuggestion function <div key={key} onClick={select}>{value}</div> Function that renders a single suggestion. This can be overridden for individual Completion types, in case they need custom rendering.

Signature:
function(suggestion: Object) => ReactElement
suggestion: Suggestion descriptor.
suggestion.key: Unique key for the suggestion element. See Dynamic Children for details.
suggestion.value: Completion value of this suggestion.
suggestion.selected: Whether this suggestion is currently selected.
suggestion.select: Autocomplete this suggestion.
renderSuggestions function <div>{suggestions}</div> Function that renders the suggestions list.

Signature:
function(suggestions: Array) => ReactElement
suggestions: Array of children rendered by renderSuggestion.
children node [] Completion types as <Completion /> elements.
limit number 15 The maximum amount of suggestions to show.
value string Current string value of the input component. Optional, useful for controlled inputs. Passed down to the input component as the value prop.
defaultValue string '' Initial string value for uncontrolled inputs.
onUpdate function () => {} Fired when the input component's value changes. Use this for controlled inputs.

Signature:
function(newValue: string) => void
newValue: null

Completion

<Completion /> elements describe different data sources. Multiple can be used in the same <AutoComplete /> component.

Name Type Default Description
trigger (required) one of:
 string
 RegExp
String that triggers this completion type.
minLength number 3 Minimum amount of characters typed before suggestions will be given.
regex RegExp null Regex to extract the current completion value from the input. Can also be used to "validate" the current completion value, so no suggestions will be provided if it's "invalid".
Uses the first capture group as the value to be completed, or the full match if there are no capture groups. For example: - /.*(@.*?)$/ + "Hello @ReA" → "@ReA" - /\w+$/ + "This is sp" → "sp"
renderSuggestion function null Function that renders a single suggestion.

Signature:
function(suggestion: Object) => ReactElement
suggestion: Suggestion descriptor.
suggestion.key: Unique key for the suggestion element. See Dynamic Children for details.
suggestion.value: Completion value of this suggestion.
suggestion.selected: Whether this suggestion is currently selected.
suggestion.select: Autocomplete this suggestion.
getCompletions function Searches the completions prop. Get an array of possible completions.

Signature:
function(matchingValue: string, props: Object) => undefined
matchingValue: Current value to be completed, as extracted using props.regex.
props: Props of this <Completion /> element.
completions array [] Optional array of completion values. This can be used if all possible completions are known beforehand. If provided, a default getCompletions function that searches this array will be used.
getText function (value, { trigger }) => ${trigger}${value} Transform a completion value to a string that will be inserted into the input component. By default, uses `${props.trigger}${value} `. (Note the space at the end! If you want to add a space once a completion is inserted, add it here.)

Signature:
function(value: undefined, props: Object) => string
value: Completion value.
props: Props of this <Completion /> element.

License

MIT