What is List.js?

List.js takes a list of items and renders them using a template.

You can provide the items in several ways:

• Inline as a JSON-serialized data-attribute
• Provided as an array to a JavaScript initializer
• Loaded from a remote url

As well as the template:

• Written as the inner HTML of the container element
• Inline as a data-attribute
• As a text or compiled template to a JavaScript initializer

Any way you configure it, the list is rendered using the same jQuery plugin, and has access to the same set of rendering helpers: pagination, sorting and filtering. This lets your list evolve from a simple hard-coded test set to your final database-driven, searchable, sortable table, without swapping in different plugins as your requirements expand.

• Usage
• Examples
  • Templates
  • Filtering / Searching
  • Sorting
  • Pagination
• Options
• API
• Events

Examples

These examples show a subset of the ways you can configure lists; they use example snippets of HTML and JavaScript that you can edit, and the rendered result is displayed below.

You can configure all of the Adcom plugins either through JavaScript as in the following examples, or through data-attributes. Read more about your options here.

Templates Render a simple table of data

To render a dynamic table, simply write the HTML necessary to render a single row. Add a unique identifier to the element that will contain all of the items (in this case, the tbody). List.js includes a minimal template syntax that lets you insert the value of any element by specifying a JSON path as data-field.

Then, initialize your list by calling .list() on the tbody with any options you need. Here, we specify the template by passing in the HTML contents of the tbody explicitly; but this happens by default if you don't specify a template, it is shown here to be explicit. You can also pass in a compiled JavaScript template. Functions will be evaluated by passing the item to the template.

<table>
  <tbody id="1">
    <tr>
      <td data-field="id"></td>
      <td data-field="name"></td>
    </tr>
  </tbody>
</table>

<script type="text/javascript">
  var items = [
    {"id": 1, "name": "one"},
    {"id": 2, "name": "two"},
    // {"id": 3, "name": "three"}
  ];
  $('#1').list({
    items: items,
    template: $('#1')[0].innerHTML
  });
</script>

Try adding additional items or more columns to see how it changes the output.

While not possible for all element types, where possible we encourage including the template inline inside the list element (as shown above) as a convention to reduce ambiguity in how a page is constructed.

Filtering and Searching

You can tie various input "triggers", such as <input> tags, to a list by adding data-target="#id" to each of them.

The value of each trigger element (either the natural value of something like a text input, or a custom value or regular expression specified with data-pattern) will be matched against every item in the list. If any of the attributes referenced in the trigger's data-fields (specified using a top-level attribute name, or a JSON path) match the value, it will be included.

Items must match every active filter to be included.

<input type="text" data-target="#2" data-filter="name" data-trigger="keyup" placeholder="Search name">
<input type="checkbox" data-target="#2" data-filter="checkbox" data-pattern="true" value="true">
<label for="checkbox">On?</label>
<input type="radio" data-target="#2" data-filter="radio" data-pattern="1" name="radio">
<label>1</label>
<input type="radio" data-target="#2" data-filter="radio" data-pattern="2" name="radio">
<label>2</label>

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Checkbox</th>
      <th>Radio</th>
    </tr>
  </thead>
  <tbody id="2">
    <tr>
      <td data-field="name"></td>
      <td data-field="checkbox"></td>
      <td data-field="radio"></td>
    </tr>
  </tbody>
</table>

<script type="text/javascript">
  var items = [
    {"name": "Number one!", "checkbox": true, radio: "1"},
    {"name": "Number two :(", "checkbox": false, radio: "2"}
  ];
  $('#2').list({ items: items });
</script>

Sorting

Any field can be sorted by adding a "sort trigger" to an element, which is triggered on click. Just add data-target and data-sort (where you specify a single field or JSON path) to an element.

On click, the sort cycles through ascending and descending, and is kept track of with the sort-ascending and sort-descending classes on the trigger. Add one of these at the start to default the sort. (number in the example below starts out with sort-ascending.)

<table class="table">
  <thead>
    <tr>
      <th class="sort-control sort-ascending" data-target="#3" data-sort="number">Number</th>
      <th class="sort-control" data-target="#3" data-sort="text">Text</th>
    </tr>
  </thead>
  <tbody id="3">
    <tr>
      <td data-field="number"></td>
      <td data-field="text"></td>
    </tr>
  </tbody>
</table>

<script type="text/javascript">
  var items = [
    {"number": 1, "text": "Beta"},
    {"number": 2, "text": "Alpha"}
  ];
  $('#3').list({ items: items });
</script>

You can customize the order / availability of the sort states by adding data-states to the trigger element, with any of the following comma-separated in the desired cycle order: ascending, descending or off (default is just the first two).

Pagination

Two configuration options can be set or updated on a list: pageSize and currentPage. The text inputs below are set to update the list's settings on change; try updating their values.

<input id="4-size" value="5" type="number" min="1">
<input id="4-page" value="1" type="number" min="1">
<div id="4">
  <button disabled data-field="#"></button>
</div>

<script type="text/javascript">
  var items = [ {"#": 1}, {"#": 2}, {"#": 3}, {"#": 4}, {"#": 5}, {"#": 6}, {"#": 7}, {"#": 8}, {"#": 9}, {"#": 10} ];
  $('#4').list({
    items: items,
    pageSize: $('#4-size').val(),
    currentPage: $('#4-page').val(),
  });

  $('#4-size').on('change', function() {
    $('#4').list({pageSize: $(this).val()});
  });
  $('#4-page').on('change', function() {
    $('#4').list({currentPage: $(this).val()});
  });
</script>

Similar to the filter and sort triggers above, clicked on an element with data-target and data-page attributes will change the current page.

Remember, you can specify any of the list-level configuration options as data-attributes on the list element itself. For example, pageSize can also be configured by adding a data-page-size attribute to the list element.

Options

A note on using data attributes versus initializer functions.

Initialization List elements

Filter triggers

Sort triggers

Page triggers

API Public methods

Events

All events with a pre and post version (such as show and shown) can be cancelled by calling .preventDefault() on the pre event.