Top

Usage

The input component is unique in the fact that it's 4 components bundled together. It provides the Input class that replaces all selects, checkboxes, and radios in a form. It also provides the InputCheckbox, InputRadio, and InputSelect classes that replace their respective individual element.

To replace all selects, checkboxes, and radios in a form, call input() on the form.

$('form').input();

By default this will replace all elements it can find within the form. To filter which elements can be replaced, specific options can be passed in.

$('form').input({
    select: 'select.with-class',
    checkbox: '.only-a-class',
    radio: 'input[type="checkbox"][data-attr]'
});

Checkboxes & Radios

To replace an individual checkbox or radio, instead of replacing all like mentioned above, use inputCheckbox() and inputRadio().

$('#checkbox').inputCheckbox();
$('#radio').inputRadio();

All checkboxes and radios will be replaced with the following markup.

<div class="custom-input">
    <!-- The original input that gets wrapped -->
    <input id="radio" type="radio" name="radio">

    <!-- The label styled to look like a radio -->
    <label for="radio" class="radio"></label>
</div>

<div class="custom-input">
    <!-- The original input that gets wrapped -->
    <input id="checkbox" type="checkbox" name="checkbox">

    <!-- The label styled to look like a checkbox -->
    <label for="checkbox" class="checkbox"></label>
</div>

No JavaScript is used for toggling the checked state, as :checked on the original input is used. To style this state, the following CSS can be used.

.custom-input input:checked + .radio { ... }
.custom-input input:checked + .checkbox { ... }
An ID attribute on the original input is required for this component to work properly.

Selects

To replace an individual select, use inputSelect().

$('#select').inputSelect();

All selects will be replaced with the following markup.

<div class="custom-input">
    <!-- The original select that gets wrapped -->
    <select>...</select>

    <div class="select">
        <div class="select-arrow"><span class="caret-down"></span></div>
        <div class="select-label">...</div>
    </div>

    <!-- The custom dropdown if native is false -->
    <div class="drop--down select-options">
        <ul>...</ul>
    </div>
</div>

Labels & Descriptions

The native selects are rather restrictive on what they can do, and how they can be customized. Because of this, a custom title, label, and description system has been implemented.

To display a default label in multi-selects when no items are selected, use getDefaultLabel.

<select name="select" title="-- Choose One --" multiple>
    ...
</select>

To display a custom label when an option is selected, use getOptionLabel. To include an optional description below the label, use getDescription.

<option value="1" title="USA">United States</option>
...
<option value="1" data-description="Hyper-Text Markup Language">HTML</option>

Notes

  • Checkboxes and radios use :checked on the original input for their active state.
  • Selected options will have .is-active applied to their parent li.
  • An .is-active class will be added to .select when a menu is open.
  • An .is-multiple class will be added to the multi-select dropdown.
  • Optgroups will be converted to .drop-heading within the dropdown.
  • Adding disabled to an option or optgroup will disable all related options.
Top

ARIA

The listbox and option roles are required for custom select drop menus when supporting ARIA.

The JavaScript component will automatically map all ARIA attributes.
Top

Options

Inherits all options from the parent component.

Option Type Default Description
copyClasses bool true Copy over classes from the original element to the custom element. Will not copy over .input classes.
Inputs
radio string input:radio CSS selector to find radios within the current element.
checkbox string input:checkbox CSS selector to find checkboxes within the current element.
select string select CSS selector to find selects within the current element.
Selects
native bool false Use native browser dropdowns instead of custom dropdowns.
hideFirst bool false Hide the first item in the menu.
hideSelected bool false Hide the selected item in the menu.
multipleFormat string count The label format for multi-selects, accepts count or list. Count will display a message similar to "1 of 10 selected", while list will list out the labels of the items selected.
countMessage string {count} of {total} selected The message to use when multipleFormat is set to count.
listLimit int 3 The max limit of labels to display when multipleFormat is set to list.
arrowContent string <span class="caret-down"></span> The content or markup to insert as the custom select arrow.
getDefaultLabel string title The select attribute to gather the default label from. The default label is used when no items are selected in multi-selects.
getOptionLabel string title The option attribute to gather the custom label from. The option label will be used to populate the selected label with, in place of using the option content.
getDescription string data-description The option attribute to gather the custom description from. The custom description will be inserted after the label within a custom dropdown.
Top

Events

Inherits all events from the parent component.

Option Event Element Event Arguments Description
onChange change.toolkit.input.select mixed:value, collection:selected Triggered when an option is selected in a custom select dropdown. The 1st argument will be the result of val(), while the 2nd argument is a list of all select option elements.
Top

Properties

Inherits all properties from the parent component.

Property Type Description
wrapper element The custom input wrapper.
element element The custom input replacement.
input element The select, checkbox, or radio element.
Selects
dropdown element The custom dropdown (uses the drop component).
multiple bool Is the current select element a multi-select.
index int The current option index when cycling with keyboard events.