ARIA Comboboxes

Expected behaviors

  • All Combobox controls are keyboard focusable unless explicitly disabled, and must include an accessible close or toggle icon for sighted mouse and mobile touch device users when applicable.
  • Interactive editable Combobox controls that use an Input+type=text element, open using the Down arrow, are navigated using Up and Down, are saved and closed by pressing Alt+Up or Enter, are canceled and closed by pressing Escape, and support uninterrupted editability when Left or Right or any other non-control key is pressed.
  • Interactive readonly Combobox controls that use an Input+type=text element, open using the Down arrow, are navigated using Up and Down, are saved and closed by pressing Alt+Up or Enter, are canceled and closed by pressing Escape, and require a toggleable triggering element for sighted mouse and mobile touch device users.
  • Interactive Combobox controls that use simulated active elements such as Divs or Spans, are readonly by default, open using the Down arrow or Enter key, are navigated using Up and Down, are saved and closed by pressing Alt+Up or Enter, are canceled and closed by pressing Escape, and act as their own actionable toggle control.

The 4X ARIA Combobox module automatically configures all required ARIA attributes and focus handling, in strict accordance with the ARIA 1.2 specification.

The following attributes are handled automatically by the Combobox module:

  • role=combobox
  • aria-activedescendant
  • aria-expanded
  • aria-controls
  • aria-autocomplete
  • aria-haspopup
  • aria-description
  • role=listbox
  • role=option
  • tabindex

HTML syntax


<label for="comboboxId"> Unique Name: </label>
<input type="text" id="comboboxId" >

For simulated active elements, any combination of HTML container markup with embedded tags is supported.


<div title="Set your location" id="comboboxId">
  <span id="valueTextId">
    <!-- Selected values will be dynamically inserted here. -->
  </span>
</div>

IMPORTANT: The focusable combobox element must not include any other active elements, otherwise these will not be accessible to non-sighted screen reader users.

It is equally important not to use aria-label on the simulated combobox to set the accessible name. Otherwise, it will prevent non-sighted screen reader users from being able to read the current value within the embedded markup.

Hidden Select element

All Combobox controls are bound to a standard Select element instance, which may be hidden within the page, or dynamically generated using JavaScript to support dynamic population via AJAX.


<select hidden id="hiddenSelectId">
  <option value="value1"> ONE </option>
  <option value="value2"> TWO </option>
</select>

To enable multiselect functionality, add the 'multiple' attribute to the hidden select element.

To set a default value for the Combobox other than index[0], add the 'selected' attribute to the default option.

JavaScript syntax


var myCombobox = new $A.Combobox({
  select: $A.get("hiddenSelectId"), // Required
  input: $A.get("comboboxId"), // Required
  childNode: $A.get("valueTextId"), // For simulated comboboxes only.
  override: {
    // DC API overrides
  }
});

// Configure settings here prior to invocation

// Then invoke the Combobox for auto-rendering when interacted with.

myCombobox.start();

Parameters

  1. A configuration map to customize behaviors and options

Configuration

{

// The hidden Select element DOM node that will be bound to the Combobox control.
select: selectElementDOMNode ,

// The focusable role=combobox element that will be bound to the hidden Select element.
input: inputDOMNode ,

// The embedded child container element where the value text will be dynamically updated. This is only applicable when the combobox element is not a native HTML input or textarea element.
childNode: optionalChildDOMNode,

// An optional override of DC object properties and methods when instantiated.
override: {
// DC API overrides
}

}

Programmatic control

After a Combobox control is instantiated, the following public properties and methods are available.

Methods

// Set the listbox to render all Select Options regardless of the current value
myCombobox.setShowAll(Boolean); // Default: False

// Enable full listbox content browsing from the keyboard when the down arrow key is pressed. (Applicable only when the value is empty.)
myCombobox.setShowAllIfEmpty(Boolean); // Default: False

// Set the listbox to render only Select Options that match the substring value
myCombobox.setSubstringMatch(Boolean); // Default: False

// Set the listbox to render only Select Options that include all of the space delimited words in the current value
myCombobox.setWordMatch(Boolean); // Default: False

// Set the Combobox to automatically display the currently selected value within the hidden Select element onStart
myCombobox.setDefault(Boolean); // Default: True

// Set the currently selected listbox value to automatically be saved when focus moves away from the Combobox control
myCombobox.setAutoComplete(Boolean); // Default: False

// Set the parent/child tag markup structure for the dynamically rendered listbox
myCombobox.setTags({
parentTag: 'ul',
childTag: 'li'
});

// Set dynamic class names
myCombobox.setClassNames({
toplevelClass: 'toplevel-div clearfix', // Top level Div class of Combobox listbox
middleClass: 'middle-div clearfix', // Mid level Div class of Combobox listbox
listboxClass: 'listbox clearfix', // // parentTag class
optionClass: 'option clearfix', // childTag class
activeClass: 'active', // Currently active Combobox listbox option
toggleClass: 'pressed' // Pressed state class of the altTrigger element
});

// Set CSS autopositioning relative to the triggering Combobox element.
// Accepted 4X API values between 0-disabled-default and 12
// For details, view the help doc at: Help/DC API/DC Object Configuration/Visual Effects
myCombobox.setAutoPosition(Number); // Default: 0

// Set a positive or negative top/left offset to be applied to the autoPosition property calculation
myCombobox.setOffset({
top: Number,
left: Number
});

// Set the number of listbox options to render when displayed
myCombobox.setSize(Number); // Default: 5

// Set a different element to act as an autoPosition focus element instead of the Combobox control
myCombobox.setPosAnchor(alternateDOMNode); // Will not change the DOM insertion point and reading order

// Set a different element to act as an insertion point and autoPosition focus element instead of the Combobox control
myCombobox.setTargetNode(alternateDOMNode); // Will change the DOM reading order

// Invoke the Combobox control and apply all saved settings
myCombobox.start();

// Close the Combobox control and pause functionality
myCombobox.stop();

// Manually open the Combobox listbox using all applied settings
myCombobox.open();

// Set a handler to execute every time the Combobox listbox is rendered
myCombobox.onOpen(function(dc){
// this = the Combobox control
// dc = the DC object instance for the Combobox listbox
});

// Manually close the Combobox listbox
myCombobox.close();

// Set a handler to execute every time the Combobox listbox is closed
myCombobox.onClose(function(dc){
// this = the Combobox control
// dc = the DC object instance for the Combobox listbox
});

// Set a toggle control to open or close the Combobox listbox
// Must always be set when implementing readonly Input+type=text elements to ensure sighted mouse and mobile touch device support
myCombobox.setAltTrigger(toggleElementDOMNode);

// Set a handler to execute every time the toggle altTrigger element is activated
myCombobox.onTriggerChange(function(altTriggerElement, toggleState){
// this = altTriggerElement
// toggleState = true or false
});

// Set a handler to execute every time a new value is saved to the Combobox control
// This will override the default functionality
myCombobox.onSelect(function(optionName, optionValue, comboboxControl, selectElement){
// this = comboboxControl
// optionName = the visible string for the hidden Select option that is highlighted.
// optionValue = the value attribute for the hidden Select option that is selected. This parameter changes to an array of selected option nodes when multiple is set instead.
// comboboxControl = the Combobox control element
// selectElement = the hidden Select element
// Save the new value accordingly
// then return the saved string to prevent auto rerendering of the Combobox listbox
return 'saved string';
});

// Set multiple divider to break up list item markup properly when updated.
// Automatically becomes available when the multiple attribute is set on the hidden select element.
myCombobox.setMultipleDivider(function(values){
// 'values' is an array of string names for the selected option nodes.
return values.join('  ');
});

// Clear all selected options when multiple is set on the hidden select element.
myCombobox.clearAll();

// Enable auto saving of checked options, even when typing to narrow the filtered list of options at the same time.
// Applicable only when Multiselect is enabled.
myCombobox.setAutoSaveIfChecked(Boolean); // Default: False

// Set a character minimum when typing into an editable combobox before autosuggested options are rendered.
myCombobox.setCharMin(#); // Default = 0

// Get the current value of the hidden select element
// Returns a value property string for single select elements, or an array of selected option DOM nodes when the multiple attribute is set on the select element.
myCombobox.getValue();

// Manually resynchronize the hidden Select to rebuild available Options for the Combobox listbox
// This can be used to repopulate rendered options after remote API queries via AJAX cause the hidden Select to contain new Options
myCombobox.update();

// Set a string to be announced to screen reader users when the Combobox control receives focus
myCombobox.setPromptText(String); // Default: ''

// Set a name for the offscreen Close link for screen reader users
// Necessary for non-sighted touch screen device users to detect the end of the Combobox listbox when rendered
// To disable the offscreen Close link when needed, pass a null value ("") to the method.
myCombobox.setCloseText(String); // Default: 'Close Popup'

Properties

// Access the hidden Select element DOM node
var selectElement = myCombobox.select;

// Access the role=combobox element DOM node
var comboboxElement = myCombobox.combobox;