Pure Typeahead

Originally built for a talk at UtahJS Conf. The Pure Typeahead is a composable typeahead component for React that allows you to build whatever kind of typeahead experience you need without configuration.

Installation

$ yarn add pure-typeahead

or

$ npm install --save pure-typeahead

In your application JavaScript file:

import { Typeahead, TypeaheadInput, TypeaheadResultsList, TypeaheadResult } from 'pure-typeahead';

Due to vast styling difference between typeahead experiences, this typeahead does not provide any styles out of the box. Please see demo/src/styles/index.js for an example of how the typeahead can be styled.

Dependencies

This package has no dependencies, but does have React 16 as a peer dependency. The component will not work with lower versions of React.

API

This component consists of four React components: Typeahead, TypeaheadInput, TypeaheadResultsList, and TypeaheadResult.

Typeahead component

The Typeahead component wraps the other, more functional component. It's purpose is to orchestrate the interactions of its children components. The Typeahead component needs a TypeaheadInput component and a TypeaheadResultsList component as direct children. It can have other children as well. For CSS targeting purposes, the Typeahead component produces a custom element tag, <pure-typeahead>, in the rendered DOM.

|Name|Required|Type|Default Value|Description| |----|--------|----|-----------| |onDismiss|optional|function|No-op function|This function is called when the typeahead is dismissed when the user presses the escape key| |onBlur|optional|function|No-op function|This function is called when the entire typeahead component is blurred. If you want to listen to blurs on the input, this is the place to do it|

TypeaheadInput component

The TypeaheadInput component is the input where the user will type their typeahead query. For accessibility to work properly, you need to use TypeaheadInput instead of a plain <input> element.

Props

|Name|Required|Type|Default Value|Description| |----|--------|----|-----------| |value|required|string|N/A|The value of the input. This input is a controlled component, so the value must be provided and updated through onChange.| |type|optional|string|'text'|The type of input to be used. Don't use 'checkbox' or 'radio' and expect this thing to work.| |placeholder|optional|string|none|The placeholder text to be placed in the input.| |onChange|required|function|N/A|The function to be called when the value of the input changes. This is where you will likely query for new typeahead results. You also must update the value prop within this function.| |onKeyDown|optional|function|No-op function|Passes through the input's onKeyDown function| |onKeyUp|optional|function|No-op function|Passes through the input's onKeyUp function| |onBlur|optional|function|No-op function|Passes through the input's onBlur function| |onFocus|optional|function|No-op function|Passes through the input's onFocus function|

TypeaheadResultsList component

The TypeaheadResultsList component wraps the TypeaheadResult components. It expects to have TypeaheadResult components as direct children, but can also have other components as children. For example, you can add <h3>s as headers between groups of results. You can also add an <svg> as a loading spinner, or a <p> describing that no results were found. Only TypeaheadResult components will be navigable with the arrow keys and selectable with the mouse. Other children will be skipped.

TypeaheadResult component

This component, which must be a direct child of the TypeaheadResultsList component, is where you describe one of the results of the typeahead. You can add anything you want as a child of this component, including text, images, and buttons.

Props

|Name|Required|Type|Default Value|Description| |----|--------|----|-----------| |onSelect|required|function|N/A|This function will be called when the typeahead is selected, whether by click or by keyboard interaction.| |onHighlight|optional|function|No-op function|This function will be called when the typeahead is highlighted through keyboard interaction|

Examples

The typeahead doesn't do much on its own; it must be properly composed to work correctly. As such, some examples are in order.

Basic typeahead, local data

import React, { Component } from 'react';

import { cities } from './cities';
import Typeahead from '../../src/Typeahead';
import TypeaheadInput from '../../src/TypeaheadInput';
import TypeaheadResultsList from '../../src/TypeaheadResultsList';
import TypeaheadResult from '../../src/TypeaheadResult';

class Demo extends Component {
  state = {
    results: [],
    taValue: '',
    selectedResult: null
  }

  typeaheadInputChange(evt) {
    const { value: str } = evt.target;
    const results = cities.filter(
      city => city.name.match(new RegExp(str, 'i'))
    );
    this.setState({
      taValue: str,
      results
    });
  }

  resultSelected(result) {
    this.setState({
      selectedResult: result,
      results: [],
      taValue: ''
    });
  }

  render() {
    const { selectedResult } = this.state;

    return [
      <Typeahead key="typeahead">
        <TypeaheadInput
          value={this.state.taValue}
          onChange={(evt)=> this.typeaheadInputChange(evt)}
        />
        <TypeaheadResultsList>
          {this.state.results.map(result => (
            <TypeaheadResult
              onSelect={() => this.resultSelected(result)}
            >
              {result.name}
            </TypeaheadResult>
          ))}
        </TypeaheadResultsList>
      </Typeahead>,
      (selectedResult &&
        <div key="selected-result">
          <h2>{selectedResult.name}</h2>
          <h3>{selectedResult.county} County</h3>
          <h3>{selectedResult.population} pop.</h3>
        </div>
      )
    ];
  }

}

export default Demo;

Typeahead with groups of results and headers

import React, { Component } from 'react';

import { cities } from './cities';
import Typeahead from '../../src/Typeahead';
import TypeaheadInput from '../../src/TypeaheadInput';
import TypeaheadResultsList from '../../src/TypeaheadResultsList';
import TypeaheadResult from '../../src/TypeaheadResult';

class Demo extends Component {
  state = {
    results: [],
    taValue: '',
    selectedResult: null
  }

  typeaheadInputChange(evt) {
    const { value: str } = evt.target;
    const results = cities.filter(
      city => city.name.match(new RegExp(str, 'i'))
    );
    this.setState({
      taValue: str,
      results
    });
  }

  resultSelected(result) {
    this.setState({
      selectedResult: result,
      results: [],
      taValue: ''
    });
  }

  render() {
    const { results, selectedResult } = this.state;
    // Group cities by county
    const counties = results.reduce((acc, city) => {
      if (acc[city.county]) {
        acc[city.county].push(city);
      } else {
        acc[city.county] = [city];
      }
      return acc;
    }, {});

    return [
      <Typeahead key="typeahead">
        <TypeaheadInput
          value={this.state.taValue}
          onChange={(evt)=> this.typeaheadInputChange(evt)}
        />
        <TypeaheadResultsList>
          {Object.keys(counties).reduce((arr, county) => {
            return [
              ...arr,
              // Display county name at the top of each county group
              (<h3 key={county}>{county}</h3>),
              ...(counties[county].map(city => (
                <TypeaheadResult onSelect={() => this.resultSelected(city)}>{city.name}</TypeaheadResult>
              )))
            ]
          }, [])}
        </TypeaheadResultsList>
      </Typeahead>,
      (selectedResult &&
        <div key="selected-result">
          <h2>{selectedResult.name}</h2>
          <h3>{selectedResult.county} County</h3>
          <h3>{selectedResult.population} pop.</h3>
        </div>
      )
    ];
  }

}

export default Demo;