Clusterize.js

Tiny plugin to display large data sets easily

May it be used for anything other than a table? Sure!

Quickstart

bower install clusterize

npm install clusterize.js

Include it on your page

<link href="./clusterize.css" rel="stylesheet">
<script src="./clusterize.min.js"></script>

Usage

<!--HTML-->
<div class="clusterize">
  <table>
    <thead>
      <tr>
        <th>Headers</th>
      </tr>
    </thead>
  </table>
  <div id="scrollArea" class="clusterize-scroll">
    <table>
      <tbody id="contentArea" class="clusterize-content">
        <tr class="clusterize-no-data">
          <td>Loading data…</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

<!--HTML-->
<div class="clusterize">
  <table>
    <thead>
      <tr>
        <th>Headers</th>
      </tr>
    </thead>
  </table>
  <div id="scrollArea" class="clusterize-scroll">
    <table>
      <tbody id="contentArea" class="clusterize-content">
        <tr><td>First row</td></tr>
        <tr><td>Second row</td></tr>
        <tr><td>…</td></tr>
      </tbody>
    </table>
  </div>
</div>

<!--HTML-->
<div id="scrollArea" class="clusterize-scroll">
  <ol id="contentArea" class="clusterize-content">
    <li class="clusterize-no-data">Loading data…</li>
  </ol>
</div>

<!--HTML-->
<div id="scrollArea" class="clusterize-scroll">
  <ol id="contentArea" class="clusterize-content">
    <li>First row</li>
    <li>Second row</li>
    <li>…</li>
  </ol>
</div>

<!--HTML-->
<div id="scrollArea" class="clusterize-scroll">
  <ul id="contentArea" class="clusterize-content">
    <li class="clusterize-no-data">Loading data…</li>
  </ul>
</div>

<!--HTML-->
<div id="scrollArea" class="clusterize-scroll">
  <ul id="contentArea" class="clusterize-content">
    <li>First row</li>
    <li>Second row</li>
    <li>…</li>
  </ul>
</div>

<!--HTML-->
<div id="scrollArea" class="clusterize-scroll">
  <div id="contentArea" class="clusterize-content">
    <div class="clusterize-no-data">Loading data…</div>
  </div>
</div>

<!--HTML-->
<div id="scrollArea" class="clusterize-scroll">
  <div id="contentArea" class="clusterize-content">
    <div>First row</div>
    <div>Second row</div>
    <div>…</div>
  </div>
</div>

// JavaScript
var data = ['<tr>…</tr>', '<tr>…</tr>', …];
var clusterize = new Clusterize({
  rows: data,
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var clusterize = new Clusterize({
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var data = ['<li>…</li>', '<li>…</li>', …];
var clusterize = new Clusterize({
  rows: data,
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var clusterize = new Clusterize({
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var data = ['<li>…</li>', '<li>…</li>', …];
var clusterize = new Clusterize({
  rows: data,
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var clusterize = new Clusterize({
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var data = ['<div>…</div>', '<div>…</div>', …];
var clusterize = new Clusterize({
  rows: data,
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

// JavaScript
var clusterize = new Clusterize({
  scrollId: 'scrollArea',
  contentId: 'contentArea'
});

Options

Methods

Callbacks

// Callbacks usage example
var clusterize = new Clusterize({
  …
  callbacks: {
    clusterWillChange: function() {},
    clusterChanged: function() {},
    scrollingProgress: function(progress) {}
  }
});

Playground

FAQ

• Should rows be the same height?
  This is not critical, but it's highly recommended that the rows are the same height. Row height is determined during initialization, picking some of the first rows and then using those for all calculations.
• How to scroll programmatically?
  Use native .scrollTop

  
  var clusterize = new Clusterize({
    rows: rows,
    scrollId: 'scrollElemId',
    contentId: 'contentElemId'
  });
  
  document.getElementById('scrollElemId').scrollTop = 500;
  

• How to attach an event listener to rows?
  Use event delegation ^{[1, 2]}

  
  // JavaScript
  var clusterize = new Clusterize({
    rows: rows, //['<tr>…</tr>', …]
    scrollId: 'scrollElemId',
    contentId: 'contentElemId'
  });
  
  document.getElementById('contentElemId').onclick = function(e) {
    e = e || event;
    var target = e.target || e.srcElement;
    if(target.nodeName != 'TR') return;
    // do stuff with row
  }
  

  
  // jQuery
  var clusterize = new Clusterize({
    rows: rows, //['<tr>…</tr>', …]
    scrollId: 'scrollElemId',
    contentId: 'contentElemId'
  });
  
  $('#contentElemId').on('click', 'tr', function() {
    // do stuff with row
  });
  

• How to implement search?
  Search functionality should be provided by yourself. Clusterize.js is only responsible for presentation. Here is an example of how multi-column search may be implemented. Checkout out demo at CodePen

  
  <!--HTML-->
  <input type="text" id="search"/>
  
  <div class="clusterize">
    <table>
      <thead></thead>
    </table>
    <div id="scrollArea" class="clusterize-scroll">
      <table>
        <tbody id="contentArea" class="clusterize-content">
          <tr class="clusterize-no-data">
            <td>Loading data…</td>
          </tr>
        </tbody>
      </table>
    </div> 
  </div>

  
  // JavaScript
  var rows = [],
      search = document.getElementById('search');
  
  /* Fill array with data
   *
   * Params:
   * values *array*  - value of each field (in case use of table)
   *        example: ['1st TD content', '2nd TD content'] for table
   *                 ['list's LI item content'] for list
   * markup *string* - markup that will be added to the DOM
   * active *bool*   - specifies if row is suitable by search phrase
  */
  for(var i = 1; i <= 500; i++){
    rows.push({
      values: [i, i*100/500+'%'],
      markup: '<tr>' +
                '<td>' + i + '</td>' +
                '<td>' + (i*100/500+'%') + '</td>' +
              '</tr>',
      active: true
    });
  }
  
  /*
  * Fetch suitable rows
  */
  var filterRows = function(rows) {
    var results = [];
    for(var i = 0, ii = rows.length; i < ii; i++) {
      if(rows[i].active) results.push(rows[i].markup)
    }
    return results;
  }
  
  /*
  * Init clusterize.js
  */
  var clusterize = new Clusterize({
    rows: filterRows(rows),
    scrollId: 'scrollArea',
    contentId: 'contentArea'
  });
  
  /*
  * Attach listener to search input tag and filter list on change
  */
  var onSearch = function() {
    for(var i = 0, ii = rows.length; i < ii; i++) {
      var suitable = false;
      for(var j = 0, jj = rows[i].values.length; j < jj; j++) {
        if(rows[i].values[j].toString().indexOf(search.value) + 1)
          suitable = true;
      }
      rows[i].active = suitable;
    }
    clusterize.update(filterRows(rows));
  }
  search.oninput = onSearch;

• How to keep table headers synced?
  In case you use table you may already noticed that headers should be placed in separated table so you may be wondered how to keep headers synced with table content. Here is example of how headers sync (including columns width, horizontal scroll position) may be implemented. Checkout out demo at CodePen
  P.s. for brevity jQuery and Lodash were used

  
  <!--HTML-->
  <div class="clusterize">
    <div class="clusterize-headers">
      <table id="headersArea">
        <thead>
          <tr>
            <td>ID</td>
            <td>Content</td>
            <td>Additional</td>
          </tr>
        </thead>
      </table>
    </div>
    <div id="scrollArea" class="clusterize-scroll">
      <table>
        <tbody id="contentArea" class="clusterize-content">
          <tr class="clusterize-no-data">
            <td>Loading data…</td>
          </tr>
        </tbody>
      </table>
    </div>
  </div>

  
  /* CSS */
  
  /* To force exceed overflow-x limit for demo purposes */
  td {
    white-space: nowrap;
  }
  
  .clusterize-headers {
    overflow: hidden;
  }

  
  // JavaScript
  var lorem = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.Lorem ipsum dolor sit amet.';
  
  var $scroll = $('#scrollArea');
  var $content = $('#contentArea');
  var $headers = $("#headersArea");
  
  var data = [];
  
  /**
   * Makes header columns equal width to content columns
   */
  var fitHeaderColumns = (function() {
    var prevWidth = [];
    return function() {
      var $firstRow = $content.find('tr:not(.clusterize-extra-row):first');
      var columnsWidth = [];
      $firstRow.children().each(function() {
        columnsWidth.push($(this).width());
      });
      if (columnsWidth.toString() == prevWidth.toString()) return;
      $headers.find('tr').children().each(function(i) {
        $(this).width(columnsWidth[i]);
      });
      prevWidth = columnsWidth;
    }
  })();
  
  /**
   * Keep header equal width to tbody
   */
  var setHeaderWidth = function() {
    $headers.width($content.width());
  }
  
  /**
   * Set left offset to header to keep equal horizontal scroll position
   */
  var setHeaderLeftMargin = function(scrollLeft) {
    $headers.css('margin-left', -scrollLeft);
  }
  
  /**
   * Emulate data fill
   */
  for (var i = 1; i <= 5000; i++) {
    var content = lorem.slice(0, _.random(0, lorem.length));
    data.push('<tr>\
      <td>' + i + '</td>\
      <td>' + _.repeat(content, 3) + '.</td>\
      <td><button>Button</button></td>\
    </tr>');
  }
  
  var clusterize = new Clusterize({
    rows: data,
    scrollId: 'scrollArea',
    contentId: 'contentArea',
    callbacks: {
      clusterChanged: function() {
        fitHeaderColumns();
        setHeaderWidth();
      }
    }
  });
  
  /**
   * Update header columns width on window resize
   */
  $(window).resize(_.debounce(fitHeaderColumns, 150));
  
  /**
   * Update header left offset on scroll
   */
  $scroll.on('scroll', (function() {
    var prevScrollLeft = 0;
    return function() {
      var scrollLeft = $(this).scrollLeft();
      if (scrollLeft == prevScrollLeft) return;
      prevScrollLeft = scrollLeft;
  
      setHeaderLeftMargin(scrollLeft);
    }
  }()));

• How to handle table with table-layout: fixed?
  In addition to external thead'ers, duplicate thead with empty cells inside table and set width for both of them. This trick will force browser to render all columns with specified width. Here is example of required markup. Checkout out demo at CodePen
  

  
  <!--HTML-->
  <div class="clusterize">
    <table class="table">
    
      <!-- Visual headers -->
      <thead>
        <tr>
          <td>Col1</td>
          <td>Col2</td>
          <td>Col3</td>
          <td>Col4</td>
        </tr>
      </thead>
    </table>
    <div id="scrollArea" class="clusterize-scroll">
      <table class="table">
      
        <!-- Hidden helper headers to keep columns width (specified by css), td's must be empty -->
        <thead>
          <td></td>
          <td></td>
          <td></td>
          <td></td>
        </thead>
        <tbody id="contentArea" class="clusterize-content">
          <tr class="clusterize-no-data">
  
            <!-- Note colspan which forces single td to fill whole table width -->
            <td colspan="100">Loading data…</td>
          </tr>
        </tbody>
      </table>
    </div>
  </div>

  
  /* CSS */
  
  /* Set appropriate styles for table */
  .table {
    table-layout: fixed;
    width: 550px;
  }
  
  /* It's important to set equal width for both thead's (visual and helper) */
  .clusterize thead td:nth-child(1) { width: 75px; }
  .clusterize thead td:nth-child(2) { width: 125px; }
  .clusterize thead td:nth-child(3) { width: 150px; }
  .clusterize thead td:nth-child(4) { width: 200px; }

  
  // JavaScript
  var data = [];
  for (var i = 0; i <= 5000; i++) {
     data.push('<tr>
      <td>' + i + '</td>\
      <td>width: 125px</td>\
      <td>width: 150px</td>\
      <td>width: 200px</td>\
    </tr>');
  }
  
  var clusterize = new Clusterize({
     rows: data,
     scrollId: 'scrollArea',
     contentId: 'contentArea'
  })

• How to use CSS counters?
  Since v0.18.0 Clusterize supports CSS counters.
  Counter name is clusterize-counter.
  Counters may be used for list of any type (like

  <ul>, <div>, <table>, etc...

  ), not just

  <ol>

  .
  Here's example of counters used for

  <ol>

  . If you need to apply counters to another list type then replace

  ol

  and

  li

  accordingly.

  
  /* Hide default counters */
  ol.clusterize-content {
    list-style: none;
  }
  
  /* Increment counter for every row */
  ol.clusterize-content li{
    counter-increment: clusterize-counter;
  }
  
  /* Display counter and customize it's styling whatever you like */
  ol.clusterize-content li:before {
    content: counter(clusterize-counter);
  }

Rendered structure and classses (in case you decided to use tables)

<div class="clusterize">
  <table>
    <thead>
      <tr>
        <th>Headers</th>
      </tr>
    </thead>
  </table>
  <div id="scrollArea" class="clusterize-scroll">
    <table>
      <tbody id="contentArea" class="clusterize-content">
        <tr class="clusterize-extra-row clusterize-keep-parity"></tr>
        <tr class="clusterize-extra-row clusterize-top-space" style="height:12345px;"></tr>

        <!--tr>Your (rows_in_block * blocks_in_cluster) rows</tr-->
        
        <tr class="clusterize-extra-row clusterize-bottom-space" style="height:12345px;"></tr>
      </tbody>
    </table>
  </div>
</div>

Author

If you enjoyed this you might also like: New!