A UI control to allow the user to quickly choose a single object from a list of many objects

sc-filtered-list is a UI control to allow the user to quickly choose a single object from a list of many objects.


Get Node.js. And then in a console...

npm install


This control is attached to a button. When the button is clicked a list would appear inline to allow the user to either use the mouse or keyboard to choose an item. A text input is available to allow the list to be filtered.


The FilteredList can be instantiated using data- attributes directly in the markup or manually by code.

Instantiate using data- attributes

Add data-sc-filtered-list to a <button>. Will instantiate on domready.

<button data-sc-filtered-list>

To get a reference to the instantiated object use the jQuery data method:


Instantiate using code

var filter = new FilteredList(document.querySelector('#myButton'));

Give options using the data- attribute.

<button data-sc-filtered-list data-sc-filtered-list-options='{"fuzzy": true}'>

The options object must be a properly formatted JSON string.

Give options using code.

var filter = new FilteredList(document.querySelector('#myButton'), {
  fuzzy: true
  • buttonLabel The button label (default: "Choose one")
  • fuzzy The search type. If true "dvd" will match "david" (default: false)
  • itemLabelKey The object key to use for the items label (default: "name")
  • listTitle The title above the list (default: "Select an item")
  • maxNumItems The maximum number of items in the list (default: 10)
  • maxNumItemsVisible The maximum number of items visible (default: 7)
  • width The width of the list (default: 300)
  • sort The default sort ["", "asc", "desc"] (default: "desc")
  • sortControlVisible If the sort control is visible (default: true)

To change the defaults, use the global FilteredList variable.

FilteredList.defaults.maxNumItems = 10;

The FilteredList uses an event based system with methods on, off and once.

myList.on('change', function(){});


  • change When the user selects and item and the value has changed
  • close When the list closes
  • destroy When the FilteredList is destroyed
  • filtered When the search value changes
  • itemFocus When an item in the list gains focus
  • open When the list opens
  • sort When the list is sorted
  • redraw When the list redraws itself
  • fetch When the list tries to fetch data based on the search term

CSS is provided and is required however it is plain by design. There are 2 ways to make the list pretty.

  1. Include bootstrap 3.x
  2. Write your own

The markup that is generated on instantiation is template driven. These templates can be changed if necessary.


<div class='{{config.className}}-container'>{{!config.templates.listInput}}{{!config.templates.listHeader}}{{!config.templates.listItemWrapper}}</div>


<div class='{{config.className}}-input-container'><input type='text' class='{{config.className}}-input form-control'></div>


<header class='{{config.className}}-header panel-heading'>{{!config.defaults.listTitle}}{{!config.templates.listSortToggle}}</header>


<div class='{{config.className}}-items list-group'></div>


<a href class='{{config.className}}-item list-group-item' data-cid='{{cid}}'>{{!key}}</a>


<button type='button' class='{{config.className}}-sort-toggle btn btn-default btn-xs' title='sort'></button>

Adds an array of objects/items in bulk[{
  name: "david"
}, {
  name: "max"

Add a single object/item

  name: "david"

Get the value

To get the value of the selected object/item use the value property.


Destroys the FilteredList and invalidates the object.


Any further calls to methods like destroy or data etc will return nothing.