enhanced-checkbox-list

Enhanced Checkbox Lists

Accessibly enhancing checkbox lists with filtering, toggling, select-all, and keyboard shortcuts

Try out the examples

Installation / usage

Grab from NPM and use in a module system:

npm install enhanced-checkbox-list

import EnhancedCheckboxList from 'enhanced-checkbox-list';
new EnhancedCheckboxList(document.getElementById('list'), options);

Or grab the minified JavaScript from unpkg:

<script src="https://unpkg.com/enhanced-checkbox-list"></script>

I would encourage you to use your own styling to match your site or application's design. An example stylesheet is included in the dist directory however which you can copy into your project and import into the browser.

Options

{
    /**
     * generate an input to allow filtering the list
     */
    filterable: boolean = true;

    /**
     * delay after typing in the filter input before filtering (to allow for fast typers)
     */
    filterDelay: number = 300;

    /**
     * selector above checkbox to determine which element to show/hide after filtering
     */
    itemSelector: string = `li`;

    /**
     * allow toggling visibility by generate a toggle button
     */
    togglable: boolean = true;

    /**
     * if togglable, close when clicking or blurring outside of the container/button
     */
    autoClose: boolean = false;

    /**
     * if togglable, determines initial visibility
     */
    visible: boolean = false;

    /**
     * text to use for the toggle button
     */
    toggleButtonText: string | ((listLabel: string, checkedCount: number) => string) =
        (listLabel, checkedCount) => `${listLabel} (${checkedCount})`;

    /**
     * include a custom select all control;
     * this has to be a custom element due to issues with updating
     * the indeterminate state on native checkboxes in many browsers
     */
    selectAllControl: boolean = true;

    /**
     * text for select all control
     */
    selectAllText: string = `Select all`;

    /**
     * if keyboard focus is on a checkbox, allow: home, end, pageup, and pagedown shortcuts
     * to move to first, last, -10, or +10 checkbox respectively;
     * and escape key to close the wrapper if togglable
     */
    keyboardShortcuts: boolean = true;

    /**
     * the index modifier for the pageup shortcut,
     * e.g. if on the 15th checkbox, use pageup to go to the 5th
     */
    pageUpModifier: number = -10;

    /**
     * the index modifier for the pagedown shortcut,
     * e.g. if on the 5th checkbox, use pagedown to go to the 15th
     */
    pageDownModifier: number = 10;

    /**
     * selector to use when finding the checkboxes in the list
     */
    checkboxSelector: string = `input[type="checkbox"], input[type="radio"]`;

    /**
     * control the tabindex added to custom elements generated by the module
     * in case your checkbox list sits at a certain point in the page's tabbing order
     */
    tabindex: number | string = `0`;

    /**
     * string to prepend to classes for BEM naming
     * e.g. enhanced-checkbox-list__wrapper
     */
    cssNameSpace: string = `enhanced-checkbox-list`;

    /**
     * custom class name to add to the filter text input
     */
    filterClassName: string;

    /**
     * custom class name to add to the toggle button
     */
    toggleClassName: string;

    /**
     * custom class name to add to the component wrapper
     */
    wrapperClassName: string;

    /**
     * label for the checkbox list - used for the toggle button text and
     * the label for the filter input; if not provided, the module will search for one
     * using aria-label or aria-labelledby attributes, or looking for a parent fieldset's legend
     */
    listLabel: string;

    /**
     * screen reader text added to list wrapper advising shortcut to close the wrapper
     * (if toggling enabled)
     */
    srEscapeToCloseText: string = `Esc to close`;

    /**
     * screen reader text added to filter field advising shortcut to clear filter value
     * (if filtering enabled)
     */
    srEscapeToClearText: string = `Esc to clear`;

    /**
     * screen reader text used for label explaining the search/filter input;
     * combines with listLabel if available e.g. "filter departments"
     */
    srFilterText: string = `filter`;

    /**
     * partial screen reader text used in message after filtering e.g. "12 found, 3 selected"
     */
    srFoundText: string = `found`;

    /**
     * partial screen reader text used in message after filtering e.g. "12 found, 3 selected"
     */
    srSelectedText: string = `selected`;

    /**
     * callback after a filter has run
     */
    onFilter: () => void;

    /**
     * callback once ready
     */
    onReady: () => void;

    /**
     * callback when the list is toggled visible
     */
    onShow: () => void;

    /**
     * callback when the list is toggled hidden
     */
    onHide: () => void;
}

Changelog

[1.1.0]

Added

• toggleButtonText option that accepts either a string or a function
• new update method in the API, to refetch checkboxes, and update the toggle button text and select all state, for if the selected checkboxes have been changed by external code
• checkboxSelector option

Changed

• The srEscapeToClearText is now only associated with the filter input when the input has a value
• Destroy method is now more defensive

Fixed

• Issue with the autoClose behaviour which wasn't always working when blurring off of the component
• Issue with the autoClose click and focusout events persisting if a list is removed from the DOM (but not properly destroyed) and another autoClose list with the same ID is later added and initialised