⚠️ WARNING: This project is still experimental / under development. Do not use in production. ⚠️
Accessible Typeahead
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.
Installation / Usage
Using npm
Install it by running:
npm install --save accessible-typeahead
Import it using a module system like Webpack:
Or using a script tag:
And then call the accessibleTypeahead
function, providing a suggestion engine:
{ const results = 'France' 'Germany' 'United Kingdom' }
Don't forget to include the stylesheet:
API Documentation
⚠️ WARNING: This is a work in progress and will change significantly. ⚠️
Required options
element
Type: PropTypes.instanceOf(HTMLElement)
The container element in which the typeahead will be rendered in.
source
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:
{ var results = 'France' 'Germany' 'United Kingdom' }
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
)
Type:
PropTypesshape inputValue: PropTypesfunc suggestion: PropTypesfunc
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:
France Germany United Kingdom
You can use the accessibleTypeahead.enhanceSelectElement
function to enhance it into a typeahead:
accessibleTypeahead
This will:
- Place a typeahead input field adjacent to the specified
<select>
- Default the typeahead
id
to the<select>
'sid
- 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 inlinedisplay: 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 foraccessibleTypeahead
. 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:
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):
- ljwatson/design-patterns: great accessible experience
- corejavascript/corejs-typeahead: flexible typeahead/suggestion engine architecture
- JamieAppleseed/selectToAutocomplete: ease of use
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.
License
MIT.