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;