Options & Methods

The HybridDropdown object can be configured using settings parsed at the time of object instantiation or as data- attributes on the HTML element itself. Optional functions need to be configured as object settings at the time of instantiation. See the option page for a full list of configuration settings.

For example, the following hybrid dropdown is configured to allow multiple selections limited to a maximum of 3,

let hyd = new HybridDropdown(el,{
  'limitSelection':3
});

this can also be configured on the HTML element using data- attributes,

<div id="my-list" data-limit-selection="3">
   <script type="application/json">
    {
      "":"Select a value",
     ...
    }
   </script>
</div>

Options

option	description
`dropdown`	‘portrait’\|‘landscape’\|‘none’, default is a vertical dropdown list (portrait), see this demo in the Examples section. The option `none` will display the field list from teh onset without a dropdown menu (see an example).
`gridColumns`	n force the list of options to be displayed as a grid with n columns (see an example).
`limitSelection`	default 1, -1 for unlimited, or an integer value, see the example Hybrid Dropdown with multiple limited selections.
`optionLabel`	a function to display the inner HTML label of each options in the list which by default wraps text labels in a span element. However, this setting is useful to customise additional attributes for each label such as displaying images, see the example Dropdown list with with custom labels with images.
`selectedLabel`	a function to display the selected label, see the example Customise the selected text label and default option.
`placeholder`	if a an empty value option is provided in the data list it will be used by default, else the default selected text will display this text value, see the example Customise the selected text label and default option.
`treeView`	`false` by default, setting this to true allows Tree View selection, see treeView example.
`treeGlue`	’/’ by default, use to concatenate branch values in treeView mode.
`fieldName`	‘`hybridd`’ the default field name to use for the form submission if none are provided in the HTML element, the plugin will use either the HTML `name` attribute or the `id` attribute before falling back on the default.
`tabIndex`	the tabindex value of the field used for tabbed navigation between the form fields.
`listOption`	filter function to determine if a data option is to be included in the dropdonw list. This is especially useful when needing to display a subset of the options depending on the value of another field in the form. See the example Filtering list of options to display.
`selectedValues`	`[]` an empty array by default, but can hold existing option values which show as pre-selected when the dropdown is initialised, see the example Pre-filled/pre-selected hybrid dropdown.
`checkboxes`	`true`\|`false`, by default it is set to `false` on dropdowns converted from existing `<select/>` fields and `true` for JSON dataset fields.
`colourise`	`true` by default, plugin attempts to find the font and background colours of the page and set the dropdown style properties, using the inverse for highlighted options. The active option is by default set to white font and `#0466ff` (blue) background. This can be changed, see the Styling section for more details.
`negative`	`false` by default. Setting to true will inverse the automatic colour styling applied by the plugin with the above `colourise` option set to true. So the default font colour is applied to the dropdown background and inversely the background to the font, see the Styling section.
`color`	empty by default, can be used to force the plugin to use a specific font colour with the option `colourise` set to true, see the Styling section for an example.
`backgroundColor`	empty by default, can be used to force the plugin to use a specific background colour with the option `colourise` set to true, see the Styling section for an example.

Methods

method	description
`refresh({})`	used to refresh a dropdown field, destroys the option list and reconstructs it. The method can have configuration options passed in order to modify the dropdown. This is especially useful to filter the option list by passing a new filter function, see the example Filtering list of options to display, or Visual styling change to reflect field update.

Accessing the HybridDropdown instance of a field.

the methods need to be called in the HybridDropdown instance,

let sel= document.querySelector('select#my-list');
let hyd = new HybridDropdown(sel,{});

hyd.refresh({...});

however, it may be that the initial object reference is not accessible, especially across scripts. It is still possible to access the hybrid object from the DOM HTML element which was hybridised, following the above example,

Select fields that have been hybriddised.

<select/> fields that have been converted will have the HybridDropdown object instace stored on the DOM element itself,

//select the DOM select element already converted.
let sel= document.querySelector('select#my-list.hybridddised');
let hyd = sel._hybriddd;

hyd.refresh({...});

HybridDropdown fields created using dataSet objects, the object instance is also available on the original DOM element on which the plugin was called,

//initially
let d = document.querySelector('div#custom-list');
let hyd = new HybridDropdown(sel,{});
...
//in another function or a different script.
let d = document.querySelector('div#custom-list.hybrid-dropdown');
let hyd = d._hybriddd;

hyd.refresh({...});

NOTE: for dataSet instantiated elements, the class .hybrid-dropdown differentiates between the element before and after instantiation.

Hybrid dropdown configuration

Options

Methods

Accessing the HybridDropdown instance of a field.

Select fields that have been hybriddised.

Hybrid dropdown field created from a dataSet object.