Skip to content

Public Options

Ciprian Popescu edited this page Mar 30, 2021 · 1 revision

Default Options

The tail.select constructor returns either the single instance or an Array with all available instances, if the first argument doesn't result in a single element.

tail.select("select", {
    animate: true,              // [0.3.0]      Boolean
    classNames: null,           // [0.2.0]      Boolean, String, Array, null
    csvOutput: false,           // [0.3.4]      Boolean
    csvSeparator: ",",          // [0.3.4]      String
    descriptions: false,        // [0.3.0]      Boolean
    deselect: false,            // [0.3.0]      Boolean
    disabled: false,            // [0.5.0]      Boolean
    height: 350,                // [0.2.0]      Integer, null
    hideDisabled: false,        // [0.3.0]      Boolean
    hideSelected: false,        // [0.3.0]      Boolean
    items: {},                  // [0.3.0]      Object
    locale: "en",               // [0.5.0]      String
    linguisticRules: {          // [0.5.9]      Object
        "е": "ё",
        "a": "ä",
        "o": "ö",
        "u": "ü",
        "ss": "ß"
    },
    multiple: false,            // [0.2.0]      Boolean
    multiLimit: Infinity,       // [0.3.0]      Integer, Infinity
    multiPinSelected: false,    // [0.5.0]      Boolean
    multiContainer: false,      // [0.3.0]      Boolean, String
    multiShowCount: true,       // [0.3.0]      Boolean
    multiShowLimit: false,      // [0.5.0]      Boolean
    multiSelectAll: false,      // [0.4.0]      Boolean
    multiSelectGroup: true,     // [0.4.0]      Boolean
    openAbove: null,            // [0.3.0]      Boolean, null
    placeholder: null,          // [0.2.0]      String, null
    search: false,              // [0.3.0]      Boolean
    searchConfig: [             // [0.5.13]     Array
        "text", "value"
    ],
    searchDisabled: true,       // [0.5.5]      Boolean
    searchFocus: true,          // [0.3.0]      Boolean
    searchMarked: true,         // [0.3.0]      Boolean
    searchMinLength: 1,         // [0.5.13]     Integer
    sortItems: false,           // [0.3.0]      String, Function, false
    sortGroups: false,          // [0.3.0]      String, Function, false
    sourceBind: false,          // [0.5.0]      Boolean
    sourceHide: true,           // [0.5.0]      Boolean
    startOpen: false,           // [0.3.0]      Boolean
    stayOpen: false,            // [0.3.0]      Boolean
    width: null,                // [0.2.0]      Integer, String, null
    cbComplete: undefined,      // [0.5.0]      Function
    cbEmpty: undefined,         // [0.5.0]      Function
    cbLoopItem: undefined,      // [0.4.0]      Function
    cbLoopGroup: undefined      // [0.4.0]      Function
});

Options

animate

bool
This options animates the open / close sequence of the tail.select dropdown field. Therefore it uses the className 'idle' during the animation.

classNames

string|array|bool
This options adds additional classNames to the main tail.select element. You can define your class names as space-separated string or as array. Use true to copy the class names of the source select field.

csvOutput

bool
This option will add a hidden input field, which takes over the name attribute of the source select field and contains the selected values - separated with the option separator defined in csvSeparator.

csvSeparator

string
This option defines the separator, which is used for the option csvOutput.

descriptions

string
This option will enable the 'description' option on the respective tail.select instance. To add a description to an option just use the 'data-description' attribute on the respective HTML option element.

deselect

bool
This option allows to deselect single select fields, which theoretically isn't possible in HTML. If enabled, tail.select will use <option>.hasAttribute("selected") instead of the <option>.selected variable. Please note: This option affects single select fields only!

disabled

bool
This option sets the 'disabled' attribute of the respective tail.select instance and gets overwritten by the source select element during the initialization.

height

string|int
This options configures the maxHeight of the tail.select dropdown popup field. Since version 0.4.0, it's no longer supported to pass null and the default has been changed to 350(px).

hideDisabled

bool
This option will hide all disabled options within the tail.select dropdown list.

hideSelected

bool
This option will hide all selected options within the tail.select dropdown list.

items

object
This option can contain additional options, which should be shown within the tail.select instance (The respective items gets also created in the source select element). Check our the 'tail.select.options' documentation for more informations!

locale

string
This option allows to set / change the localization / language. Please make sure to load the respective language strings AFTER the main tail.select JavaScript file.

lingusticRules

object
This options allows you to configure the search function, by using some linguistic regexp magic. This magic allows you to handle special letters like default ones. For exmaple: the russian "ё" is handles as "e" (ans vica versa), so it didn't matter, which of them you're using on the search.

multiple

bool
This option sets the 'single / multiple' option of the respective tail.select instance and gets overwritten by the source select element during the initialization.

multiLimit

int
This option allows to limit the selection to the respective number. Use Infinity to disable any limit, use 0 to allow no selection at all. Please note: This option affects multiple select fields only!

multiPinSelected

bool
Use true to "pin" selected options on the top of the dropdown list. Please note: This option is only available on multiple select fields!

multiContainer

string|bool
This option allow on string-based element selector only. If passed it will move special handle objects to the respective element. You can also use true which moves the selected options into the label element of the tail.select instance! Please note: This option is only available on multiple select fields!

multiShowCount

bool
This option shows a small counter to the left of the tail.select label. Please note: This option is only available on multiple select fields!

multiShowLimit

bool
This option shows the number of selectable options next to the counter number. Please note: This option is only available on multiple select fields!

multiSelectAll

bool
This option will show a "Select All" / "Unselect All" action buttons on top of the dropdown list, which (un)selects all available options!

multiSelectGroup

bool
This option will show a "All" / "None" Button on each Optgroup header, which (un)selects all options within this group!

openAbove

bool
This option determines where the tail.select dropdown field is located. Use true to open the dropdown field always above the select field, use 'false' for the opposite or just keep it to null, which will use the bottom location unless there is no room left for it.

placeholder

string
This option sets the placeholder to the respective tail.select element, which is invisible on single not-deselectale fields. This option gets overwritten by the 'placeholder' (or as fallback on the 'data-placeholder') attribute on the respective source select field. If not placeholder is set at all 'tail.select.strings.placeholder' will be used!

search

bool
This option will enable the search input field within the tail.select dropdown field.

searchConfig

string|array|function
This option allows you to pass a single instruction as STRING to the search engine, multiple as ARRAY or an own search function (which MUST return true or false, depending if the option should be shown in the list or not)

The available options:

  • "text" (default): Performs a default textual search.
  • "regex": Use a regular expression pattern to perform the search.
  • "case": Enables case sensitive searching.
  • "word": Enables searching only whole words.
  • "exactglyphes": Disable matching languageRules{...} replacement.
  • "value" (default): Search the options value.
  • "attributes": Search into options' attributes.
  • "any": Search both into value and attributes.

Note1 If both or neighter of "text" and "regex" options are provided, "text" is used. Note2 If "any" is provided, adding "value" or "attributes" have no effect. Providing both "value" and "attributes" act as provides "any"

searchDisabled

boolean
This option allows you to search also disabled options, which can be selected by the user. The default is true, set it to false to exclude disabled options.

searchFocus

bool
This option will set the focus automatically to the search input field, when the dropdown field gets opened.

searchMarked

bool
This option will 'mark' the search term on the respective option text within the given results.

searchMinLength

ingeger
This option allows you to adapt the minimum amount of characters to trigger / start a search query. The default is 3, which is the best choise in the most use-cases.

sortItems

string|function
This option configures the sort order of the shown options within the tail.select dropdown element. You can use ASCDESC or your own callback sort compareFunction!

sortGroups

string|function
This option configures the sort order of the shown option groups within the tail.select dropdown element. You can use ASCDESC or your own callback sort compareFunction!

sourceBind

bool
This option will set an event listener to the source select element. Thus, all changes to the source element will be taken over in the tail.select instance!

sourceHide

bool
This option will hide, set the display: none styling, to the source select element. This option will also check if the source select field has a display: none; or visibility: hidden; property and adapt this to the main tail.select container

startOpen

bool
This option will call the .open() method directly after the tail.select initialization has been completed.

stayOpen

bool
This option will prevent the call of the .close() method at the typical events, but you can still call the .close() method on your own to close the dropdown field. You can pass true to stay open at all costs or false to close whenever the selection field gets forsaken. Since 0.5.0 you can also pass null, which closes whenever the user clicks "outside" of the select element, but will still stay open when the user selects an option!

width

string|int
This options configures the width of the tail.select field as well as for the dropdown field, you can use 'auto' to detect the current width or null (like the default) to set no width styling at all.

cbComplete

callback
This callback function gets fired every time when the .init() process of the tail.select instance has been finished / reached the end. The only argument, which gets passed, is the main tail.select container, but you can use this to access the class too!

cbEmpty

callback
This callback function gets fired every time when the Dropdown List gets rendered with no single option. Which happens on each "empty" select field and on each search which leads to no results. You function receives 2 arguments: The root .dropdown-inner element as well as the search string (on searches) or undefined otherwise.

cbLoopItem

callback
This option allows you to edit / manipulate each displayed item within the dropdown field, just pass a function, which accepts the following 3 arguments: (item , group , search <string|false>).

cbLoopGroup

callback
This option allows you to edit / manipulate each displayed group within the dropdown field, just pass a function, which accepts the following 2 arguments: (label , search <string|false>).