THIS IS AN AUTOGENERATED FILE. EDIT INDEX.JS INSTEAD.

Typeahead

Intelligently recommend entities via customizable, fuzzy recognition.

Typeahead is an enhancement upon Input which provides two built-in matching algorithms ("fuzzy" [default] and "starts-with") and supports the use of custom matching and marking functions.

In the examples below, imagine the <> in the "marks" section is a wrapping <mark> element:

1. "Starts-with" matching & marking

   <Typeahead
       algorithm={Typeahead.mode.STARTS_WITH}
       entities={[
           {text: 'apple'},
           {text: 'apricot'},
           {text: 'grape'},
       ]}
       inputProps={{value: 'a'}} />

   • matches: "apple", "apricot"
   • marks: "<a>pple", "<a>pricot"

2. "Fuzzy" matching & marking

   <Typeahead
       algorithm={Typeahead.mode.FUZZY}
       entities={[
           {text: 'apple'},
           {text: 'apricot'},
           {text: 'grape'},
       ]}
       inputProps={{value: 'a'}} />

   • matches: "apple", "apricot", "grape"
   • marks: "<a>pple", "<a>pricot", "gr<a>pe"

3. Custom matching & marking

   Optionally, you can provide your own combination of matching and marking functions. For example, loosening the matching to include unicode variants of characters could be useful, e.g. ç → c

   <Typeahead
       algorithm={{
           matcher: yourMatchFunc,
           marker: yourMarkFunc,
       }} />

Component Instance Methods

When using Typeahead in your project, you may call the following methods on a rendered instance of the component. Use refs to get the instance.

• focus() focuses the browser oon the underlying textual input for immediate text entry

• getInputNode() returns the raw underlying textual input DOM node

• getSelectedEntityText() returns the text property of the currently highlighted entity (from props.entities), or returns an empty string

• getValue() retrieves the current value of the underlying textual input

• select() programmatically creates a full selection on the underlying textual input such that a press of the Backspace key would fully clear the input

• setValue(value: string) sets the underlying textual input to the specified text and updates internal state; do not use this method when using Typeahead as a "controlled input"

Props

Note: only top-level props are in the README, for the full list check out the website.

Required Props

There are no required props.

Optional Props

<tr>
    <td>algorithm</td>
    <td><pre><code>Typeahead.mode.STARTS_WITH or

Typeahead.mode.FUZZY or object Typeahead.mode.FUZZY the mechanism used to identify and mark matching substrings; a custom set can be provided as an object (see the properties below)

<tr>
    <td>clearOnSelection</td>
    <td><pre><code>bool</code></pre></td>
    <td><pre><code class="language-js">false</code></pre></td>
    <td>if `true`, clears the input text when a (partial) match is selected</td>
</tr>

<tr>
    <td>entities</td>
    <td><pre><code>arrayOf(object)</code></pre></td>
    <td><pre><code class="language-js">[]</code></pre></td>
    <td>an array of objects that user input is filtered against; at a minimum, each object must have a `text` property and any other supplied property is passed through to the resulting DOM element</td>
</tr>

<tr>
    <td>hidePlaceholderOnFocus</td>
    <td><pre><code>bool</code></pre></td>
    <td><pre><code class="language-js">true</code></pre></td>
    <td>triggers the placeholder to disappear when the input field is focused, reappears when the user has tabbed away or focus is moved</td>
</tr>

<tr>
    <td>hint</td>
    <td><pre><code>bool</code></pre></td>
    <td><pre><code class="language-js">null</code></pre></td>
    <td>renders a disabled textfield with the full text of the currently selected input hint; will remain blank if the matched substring is not at the beginning of the user input</td>
</tr>

<tr>
    <td>hintProps</td>
    <td><pre><code>object</code></pre></td>
    <td><pre><code class="language-js">{}</code></pre></td>
    <td>any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes); applied to the `.b-typeahead-hint` HTML element</td>
</tr>

<tr>
    <td>inputProps</td>
    <td><pre><code>object</code></pre></td>
    <td><pre><code class="language-js">{
type: 'text',

} props to be passed through to the input node, .b-textual-input; this includes the standard set of React input props like defaultValue, value, name, placeholder, autoFocus, etc.

<tr>
    <td>matchWrapperProps</td>
    <td><pre><code>object</code></pre></td>
    <td><pre><code class="language-js">{}</code></pre></td>
    <td>any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes); applied to the `.b-typeahead-match-wrapper` HTML element</td>
</tr>

<tr>
    <td>offscreenClass</td>
    <td><pre><code>string</code></pre></td>
    <td><pre><code class="language-js">'b-offscreen'</code></pre></td>
    <td>the "offscreen" class used by your application; specifically to retain [ARIA navigability](http://snook.ca/archives/html_and_css/hiding-content-for-accessibility) as `display: none` excludes the element from consideration</td>
</tr>

<tr>
    <td>onComplete</td>
    <td><pre><code>function</code></pre></td>
    <td><pre><code class="language-js">noop</code></pre></td>
    <td>called when the user presses `Enter` with no autosuggest hint available, indicating that input is complete</td>
</tr>

<tr>
    <td>onEntityHighlighted</td>
    <td><pre><code>function</code></pre></td>
    <td><pre><code class="language-js">noop</code></pre></td>
    <td>called with the index of the highlighted entity due to keyboard selection</td>
</tr>

<tr>
    <td>onEntitySelected</td>
    <td><pre><code>function</code></pre></td>
    <td><pre><code class="language-js">noop</code></pre></td>
    <td>called with the index of the entity selected by the user</td>
</tr>