
- @drupal/a11y_autocomplete
- Documentation and examples
- Basic use
- Options
- Setting Options
- Required options
- Options Documentation
- allowRepeatValues (default: null)
- autoFocus (default: false)
- separatorChar (default: ',')
- firstCharacterDenylist (default: ',')
- minChars (default: 1)
- maxItems (default: 20)
- sort (default: true)
- path (default: null)
- list (default: [])
- displayLabels (default: true)
- disabled (default: false)
- cardinality (default: 1)
- inputClass (default: '')
- loadingClass (default: '')
- ulClass (default: '')
- itemClass (default: '')
- createLiveRegion (default: true)
- listZindex (default: 1)
- searchDelay (default: 300)
- inputAssistiveHint ('When autocomplete results are available use up and down arrows to review and enter to select. Touch device users, explore by touch or with swipe gestures.')
- minCharAssistiveHint (default 'Type @count or more characters for results')
- noResultsAssistiveHint (default: 'No results found')
- moreThanMaxResultsAssistiveHint (default: 'There are at least @count results available. Type additional characters to refine your search.')
- someResultsAssistiveHint (default: 'There are @count results available.')
- oneResultAssistiveHint (default: 'There is one result available.')
@drupal/a11y_autocomplete
Accessible autocomplete widget.
Documentation and examples
Basic use
Ensure the assets are included in the page
<link rel="stylesheet" href="[path]/a11y.autocomplete.css" />
<script src="[path]/a11y.autocomplete.js"></script>
Initialize
const inputGettingAutcomplete = document.querySelector('#an-input')'
const autocompleteInstance = A11yAutocomplete(inputGettingAutcomplete, options);
Options
Setting Options
Options can be set in three ways, the listed from highest precedence to lowest:
- An object literal in the input's
data-autocomplete
attribute with the format{camelCaseOptionName: value}
such as<input data-autocomplete="{maxItems: 10}" />"
-
data-autocomplete-(hyphen delimited option name)
such as<input data-autocomplete-max-items="10" />
- Via the options argument when initializing a new instance, such as
A11yAutocomplete(inputGettingAutcomplete, {maxItems: 10})
Required options
Either the list
or path
option must have a value for the Autocomplete to function.
list
is an array of predetermined items, and path
is url that provides results
based on the input value.
If both list
and path
have values, list
will take precedence. Without one
of these values set, the input will still initialize, but will have no values to return when queried.
Options Documentation
allowRepeatValues
(default: null
)
type: Boolean|null
If true
, autocomplete results can include items already included in the field.
autoFocus
(default: false
)
type: Boolean
Set to true
, to focus the first result as soon as a list of results becomes visible
separatorChar
(default: ','
)
type: string
The character used to separate multiple values in the same form
firstCharacterDenylist
(default: ','
)
type: string
Any characters in this string will not be incorporated in a search as the first
character of a query. Typically, this string should at least include the value of separatorChar
.
minChars
(default: 1
)
type: Number
Minimum number of characters that must be typed before displaying autocomplete results.
maxItems
(default: 20
)
type: Number
The maximum number of results displayed.
sort
(default: true
)
type: Boolean
When true
the results are sorted prior to display. The default sorting behavior
is alphabetical, and can be customized by overriding sortSuggestions()
.
path
(default: null)
type: null|string
This should be a URL that returns search results. By default, when an autocomplete
search begins it queries (the value of 'path')?q=(value typed in the autocomplete input)
.
How the autocomplete interacts with path
can be customized by overriding queryUrl()
list
(default: []
)
type: Array
A predefined list of autocomplete options. This can be an array of strings or objects with
label:
and value:
properties. If this array is not empty, this property will take
precedence over searching the remote resource specified in path
.
displayLabels
(default: true
)
type: Boolean
When true
, and when query results are provided as an object with label:
and value:
properties, the suggestion list
will display the item label:
, but if selected, the input will have the value set in value:
disabled
(default: false
)
type: Boolean
When true
, input events on the input will not trigger searches.
cardinality
(default: 1
)
type: Number
The number of values the input can have. Set to -1
for unlimited values.
inputClass
(default: ''
)
type: string
Additional classes that can be added to the autocomplete input.
loadingClass
(default: ''
)
type: string
Additional classes that can be added to the autocomplete input while waiting for
a query to return results
ulClass
(default: ''
)
type: string
Additional classes that can be added to the results list container <ul>
itemClass
(default: ''
)
type: string
Additional classes that can be added to each <li>
item in the results list.
createLiveRegion
(default: true
)
type: Boolean
When true
, initialization includes adding a live region specifically that will
convey autocomplete activity to assistive technology. This is typically only set
to false
if a site has a centralized live region where announcements to
assitive technology should be directed to.
listZindex
(default: 1
)
type: Number
The CSS z-index of the results list.
searchDelay
(default: 300
)
type: Number
Time to in milliseconds after input activity before an autocomplete search is
triggered.
inputAssistiveHint
('When autocomplete results are available use up and down arrows to review and enter to select. Touch device users, explore by touch or with swipe gestures.'
)
type: string
Message conveyed to assistive technology when the input is focused
minCharAssistiveHint
(default 'Type @count or more characters for results'
)
type: string
When minChar
is greater than one, this is appended to messages.inputAssistiveHint
so users are aware how many characters are needed to trigger a search. @count
is
replaced with the value of minChar
.
noResultsAssistiveHint
(default: 'No results found'
)
type: string
Message conveyed to assistive technology when the query returns no results.
moreThanMaxResultsAssistiveHint
(default: 'There are at least @count results available. Type additional characters to refine your search.'
)
type: string
Message conveyed to assistive technology when the number of results exceeds the
maximum amount set via the maxItems
option. @count
is replaced with the
value of maxItems
.
someResultsAssistiveHint
(default: 'There are @count results available.'
)
type: string
Message conveyed to assistive technology when the number of results exceeds one
and does not exceed the maximum amount set via the maxItems
option. @count
is
replaced with the number of results returned.
oneResultAssistiveHint
(default: 'There is one result available.'
)
type: string
Message conveyed to assistive technology when there is one result.