Noosphere Possibilities Maximized
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    This package has been deprecated

    Author message:

    WARNING: This project has been renamed to accessible-autocomplete. Install using accessible-autocomplete instead.

    ⚠️ WARNING: This project is still experimental / under development. Do not use in production. ⚠️

    Accessible Typeahead

    npm version Build Status gzip size

    Sauce Labs Build Status

    accessible-typeahead is a JavaScript typeahead built from the ground up to be accessible. The design goals are:

    • Accessibility: Following WAI-ARIA best practices and testing with assistive technologies.
    • User experience: Supporting a wide variety of user needs.
    • Compatibility: Working with as many browsers, devices, and assistive technologies as possible.

    Try out the examples!

    Installation / Usage

    Using npm

    Install it by running:

    npm install --save accessible-typeahead

    Import it using a module system like Webpack:

    import accessibleTypeahead from 'accessible-typeahead'

    Or using a script tag:

    <script type="text/javascript" src="node_modules/accessible-typeahead/dist/accessible-typeahead.min.js"></script>

    And then call the accessibleTypeahead function, providing a suggestion engine:

    function suggest (query, syncResults) {
      const results = [
        'United Kingdom'
      syncResults(results.filter(result => result.indexOf(query) !== -1))
      element: document.querySelector('#my-typeahead-container'),
      id: 'my-typeahead',
      source: suggest

    Don't forget to include the stylesheet:

    <link rel="stylesheet" href="node_modules/accessible-typeahead/dist/accessible-typeahead.min.css" />

    API Documentation

    ⚠️ WARNING: This is a work in progress and will change significantly. ⚠️

    Required options


    Type: PropTypes.instanceOf(HTMLElement)

    The container element in which the typeahead will be rendered in.


    Type: PropTypes.func

    Arguments: query: string, syncResults: Function

    Similar to the source argument for typeahead.js, a backing data source for suggestions. query is what gets typed into the input field, which will callback to syncResults synchronously with the array of string results to display in the menu.

    An example of a simple suggestion engine:

    function suggest (query, syncResults) {
      var results = [
        'United Kingdom'
        ? results.filter(function (result) {
            return result.toLowerCase().indexOf(query.toLowerCase()) !== -1
        : []

    Other options

    autoselect (default: false)

    Type: PropTypes.bool

    Set to true to highlight the first option when the user types in something and receives results. Pressing enter will select it.

    cssNamespace (default: 'typeahead')

    Type: PropTypes.string

    The default CSS classes use BEM with typeahead as the block name. If you already have CSS rules for .typeahead--menu or any of the other default classes, you can use this property to rename them and prevent clashes.

    TODO: Better styling docs.

    defaultValue (default: '')

    Type: PropTypes.string

    Specify a string to prefill the typeahead with.

    displayMenu (default: 'inline')

    Type: PropTypes.oneOf(['inline', 'overlay'])

    You can set this property to specify the way the menu should appear, whether inline or as an overlay.

    id (default: 'typeahead')

    Type: PropTypes.string

    The id for the typeahead input field, to use with a <label for=id>. Required if you're instantiating more than one typeahead in one page.

    minLength (default: 0)

    Type: PropTypes.number

    The minimum number of characters that should be entered before the typeahead will attempt to suggest options. When the query length is under this, the aria status region will also provide helpful text to the user informing them they should type in more.

    name (default: 'input-typeahead')

    Type: PropTypes.string

    The name for the typeahead input field, to use with a parent <form>.

    onSelect (default: () => {})

    Type: PropTypes.func

    Arguments: selected: Object

    This function will be called when the user selects an option, with the option they've selected.

    selectOnBlur (default: true)

    Type: PropTypes.bool

    Set this value to false to stop the typeahead from automatically confirming a value when it has been selected using autoselect or the keyboard and the user "blurs" (clicks outside of the component).

    showNoOptionsFound (default: true)

    Type: PropTypes.bool

    Set this value to false to not display the "No options found" template when there are no results available. Some typeaheads might intermittently display results between different search term roots (like one based on lunrjs), and as such wouldn't need to use this.

    templates (default: undefined)


      inputValue: PropTypes.func,
      suggestion: PropTypes.func

    This object defines templates (functions) that are used for displaying parts of the typeahead.

    inputValue is a function that receives one argument, the currently selected suggestion. It is used to populate the value of the input field, and should return a string.

    suggestion is a function that receives one argument, a suggestion to be displayed. It is used when rendering suggestions, and should return a string, which can contain HTML. ⚠️ Caution: because this function allows you to output arbitrary HTML, you should make sure it's trusted, and accessible.

    placeholder (default: '', ⚠️ not recommended ⚠️)

    Type: PropTypes.string

    This option will populate the placeholder attribute on the input element.

    We think placeholders have usability issues and that there are better alternatives to input placeholder text, so we do not recommend using this option.

    Progressive enhancement

    If your typeahead is meant to select from a small list of options (a few hundreds), we strongly suggest that you render a <select> menu on the server, and use progressive enhancement.

    If you have the following HTML:

    <select id="location-picker">
      <option value="fr">France</option>
      <option value="de">Germany</option>
      <option value="gb">United Kingdom</option>

    You can use the accessibleTypeahead.enhanceSelectElement function to enhance it into a typeahead:

      selectElement: document.querySelector('#location-picker')

    This will:

    • Place a typeahead input field adjacent to the specified <select>
    • Default the typeahead id to the <select>'s id
    • Default the typeahead name attribute to '' to prevent it being included in form submissions
    • Default the typeahead source to a basic one that uses any existing <option>s from the <select>
    • Hide the <select> using inline display: none
    • Set the <select>'s id to ${id}-select to decouple from any <label>
    • Upon selecting a value in the typeahead, update the original <select>

    This function takes the same options as accessibleTypeahead, with the only difference being that it uses selectElement instead of element, which needs to be an instance of HTMLSelectElement.

    Tip: To prefill the typeahead with an option[selected], you can use the defaultValue option.

    Note: The accessibleTypeahead.enhanceSelectElement function is fairly light and wraps the public API for accessibleTypeahead. If your use case doesn't fit the above defaults, try reading the source and seeing if you can write your own.

    Analytics & Tracking

    The following events get triggered on he input element during the life cycle of the typeahead:

    • onSelect - This function will be called when the user selects an option, with the option they've selected.

    Example usage:

      // … 
      onSelect: (val) => {

    Why another typeahead?

    accessible-typeahead was built after studying many existing solutions and prototyping patches to fix user experience or accessibility issues. It draws heavy inspiration from the following (and a lot of others):

    Developing locally

    Check out the CONTRIBUTING guide for instructions.

    If you want to help and want to get more familiar with the codebase, try starting with the "good for beginners" issues.




    npm i accessible-typeahead

    Downloadsweekly downloads







    last publish


    • avatar