List API





Using List.js is pretty much plug and play, but you can change some options if you feel like it.

new List(id/element, options, values);
  • id or element *required
    Id the element in which the list area should be initialized. OR the actual element itself.
  • options Object, default: undefined
    Some of the option parameters are required at some times

    • valueNames Array, default: null. *required
      If the list contains items on initialization, then this array has to contain the value names (class names) for the different values of each list item.

      <ul class="list">
              <span class="name">Jonny</span>
              <span class="city">Sundsvall</span>
      var valueNames = ['name', 'city'];
      <ul class="list">
       <li data-id="1">
         <a href="" class="link name">Jonny</a>
         <p class="born timestamp" data-timestamp="1234">1986</p>
         <img class="image" src="javve.jpg" />
      var valueNames =  [
        { data: ['id'] },
        { name: 'timestamp', attr: 'data-timestamp' },
        { name: 'link', attr: 'href' },
        { name: 'image', attr: 'src' }
    • item String, default: undefined
      ID to item template element or a string of HTML. Can also be a function which receives a values object and which must return the complete item's HTML as a string.

      var options = {
          item: "<li><span class='name'></span><span class='city'></span></li>"
      // or
      var options = {
          item: 'cool-item-id'
      // or
      var options = {
          item: function(values) {
            return `<li><span class='name'>${}</span><span class='city'>${}</span></li>`;
    • listClass String, default: "list"
      What is the class of the list-container?

    • searchClass String, default: "search"
      What is the class of the search field?

    • searchColumns Array of strings, default: undefined
      Restrict searching to just these column names? Default is to search all columns.

    • searchDelay Int default: 0
      Delay in milliseconds after last keypress in search field before search starts. 250→750 is good for very large lists.

    • sortClass String, default: "sort"
      What is the class of the sort buttons?

    • indexAsync Boolean, default: false
      If there are already items in the list to which the List.js-script is added, then should the indexing be done in a asynchronous way? Good for large lists (> 500 items).

    • page Int, default: 200
      Defines how many items that should be visible at the same time. This affects performance.

    • i Int, default: 1
      Which item should be shown as the first one.

    • pagination Boolean, default: undefined
      Read more here.

  • values Array of objects, default: undefined
    Values to add to the list on initialization.


  • listContainer Element
    The element node that contains the entire list area.

  • list Element
    The element containing all items.

  • items Array
    An Array of all Item-objects in the list.

  • visibleItems Array
    The currently visible items in the list

  • matchingItems Array
    The items matching the currently active filter and search.

  • searched Boolean
    Returns true if the list is searched.

  • filtered Boolean
    Returns true if there is an active filter.


  • add(values, callback)
    Adds one or more items to the list.

    listObj.add({ name: "Jonny", city: "Stockholm" });
    { name: "Gustaf", city: "Sundsvall" }
    , { name: "Jonas", city: "Berlin" }

    If callback is set then items are added to the list in a asynchronous way, and the callback is called when all items are added. This is especially useful when adding very many items (200+ or something), or if you just like the asynchronous coding style.

    listObj.add(arrayWithManyManyItems, function(items) {
    console.log('All ' + items.length + ' were added!');
  • remove(valueName, value)
    Removes items from the list where the value named valueName has value value. Returns the number of items that where removed.

    itemsInList = [
    { id: 1, name: "Jonny" }
    , { id: 2, name "Gustaf" }
    listObj.remove("id", 1); // return 1
  • get(valueName, value)
    Returns values from the list where the value named valueName has value value.

    itemsInList = [
    { id: 1, name: "Jonny" }
    , { id: 2, name "Gustaf" }
    listObj.get("id", 2); // return { id: 2, name "Gustaf" }
  • sort(valueName, {
      order: 'desc',
      alphabet: undefined,
      insensitive: true,
      sortFunction: undefined

    Sorts the list based on values the in the column named valueName. The alphabet option is used when you have non-english alphabet where which JavaScript don't know how to sort some characters by default.

    The default sort function is found here, if you want to use your own, read the code and check out the tests.

    listObj.sort('name', { order: "asc" }); // Sorts the list in abc-order based on names
    listObj.sort('name', { order: "desc" }); // Sorts the list in zxy-order based on names
    // Sort swedish characters correcly, case-insensitive.
    listObj.sort('name', { alphabet: "ABCDEFGHIJKLMNOPQRSTUVXYZÅÄÖabcdefghijklmnopqrstuvxyzåäö" });
    // Sort swedish characters correcly, case-sensitive.
    listObj.sort('name', { alphabet: "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvXxYyZzÅåÄäÖö" });
    // Alphabet could also be on the actual listObj via
    listObj.alphabet = "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvXxYyZzÅåÄäÖö";
  • search(searchString, columns, searchFunction)
    Searches the list

    itemsInList = [
    { id: 1, name: "Jonny Stromberg", born: 1986 }
    , { id: 2, name "Jonas Arnklint", born: 1985 }
    , { id: 3, name "Martina Elm", born: 1986 }
    , { id: 4, name "Gustaf Lindqvist", born: 1983 }
    , { id: 5, name "Jonny Strandberg", born: 1990 }
    ];'Jonny'); // Only items with name Jonny are shown (also returns these items); // Show all items in list'Jonny', ['name']); // Only search in the 'name' column

    Space-separated words match in any order using logical AND. Surround a phrase in quotes for exact matches:'Jon 198'); // Items that match Jon AND 198'"Jonny S" 1990'); // Items that match "Jonny S" AND 1990

    Optionally your own search function can be used:'Jonny', searchFunction); // Custom search for Jonny'Jonny', ['name'], searchFunction); // Custom search in the 'name' column
    function searchFunction(searchString, columns) {
      for (var k = 0, kl = listObj.items.length; k < kl; k++) {
         listObj.items[k].found = false;
         // Insert your custom search logic here, set found = true
  • clear()
    Removes all items from the list

  • filter(filterFunction)

    itemsInList = [
    { id: 1, name: "Jonny" }
    , { id: 2, name "Gustaf" }
    , { id: 3, name "Jonas" }
    listObj.filter(function(item) {
    if (item.values().id > 1) {
       return true;
    } else {
       return false;
    }); // Only items with id > 1 are shown in list
    listObj.filter(); // Remove all filters
  • size()
    Returns the size of the list.

  • show(i, page)
    Shows page number of items from i. Use for paging etc.

    itemsInList = [
    { id: 1, name: "Jonny" }
    , { id: 2, name "Gustaf" }
    , { id: 3, name "Jonas" }
    , { id: 4, name "Egon" }
    , { id: 5, name "Frank" }
    , { id: 6, name "Ester" }
    ];, 3); // Display item 4,5,6 
  • update()
    Updates the current state of the list. Meaning that if you for instance hides some items with the itemObj.hide() method then you have to call listObj.update() if you want the paging to update.

  • reIndex()
    Re-index list from HTML. Good to use if the HTML has been changed by something else than List.js.

  • fuzzySearch()
    Read more here

  • on(event, callback)
    Execute callback when list have been updated (triggered by update(), which is used by a lot of methods). Use updated as the event.

    Avaliable events

    • updated
    • searchStart
    • searchComplete
    • filterStart
    • filterComplete
    • sortStart
    • sortComplete