row-selector

Selector options for rows.

Description

The DataTables rows() and row() (also optionally cells() and cell()) methods provide the ability to select rows from the table. What rows are selected and how the selector actually operates is controlled by this row-selector data type.

Options

The row selector can be given in a number of different forms, to make it easy to apply to your data and use case:

• No selector - Select all rows
• integer - Row index selector
• string - ID selector
• string - jQuery selector
• node - This may be one of the following:
  • tr - table row element
  • td - table cell element (Since: 1.10.11)
  • Any element which has a data-dt-row attribute assigned to it, or a parent (Since: 1.10.11). This can be used by extensions such as FixedColumns and Responsive to allow easy row selection.
• function - Function selector (Since: 1.10.3)
• jQuery - jQuery object of row nodes
• array - Array containing any combination of the above options

No selector

If no selector is given (more specifically undefined), then all rows are selected.

Get data for all rows in the table:

var table = new DataTable('#myTable');
var allData = table.rows().data();

integer

DataTables stores each row internally with a row index for fast look up of row information. When the selector is given as an integer, this value represents a row index (rows().indexes() / row().index()).

Row index 0 data:

var table = new DataTable('#myTable');
var data = table.row( 0 ).data();

Find data using row indexes:

var table = new DataTable('#myTable');

// Find indexes of rows which have `Yes` in the second column
var indexes = table.rows().eq( 0 ).filter( function (rowIdx) {
    return table.cell( rowIdx, 1 ).data() === 'Yes' ? true : false;
} );

// Add a class to those rows using an index selector
table.rows( indexes )
    .nodes()
    .to$()
    .addClass( 'highlight' );

string - #ID

DataTables row selector is optimised for IDs as it is natural to wish to select rows by unique information. This is distinct from a jQuery selector as DataTables can optimise this selector type so as to not involve the DOM - also allowing an id row selector to operate on rows which have not yet had their DOM nodes created (when using deferRender for extra speed).

With dynamically sourced data, the id assigned to the row is identifier using the rowId option. The data used as the id can be of any value, although it must be unique in the table.

To use an id selector, simply prefix the id value for the row you wish to select with a number sign: #. The value that follows is taken as the id. Unlike jQuery this value does not need to be escaped - although this means that an id selector must be used alone (e.g. a class name cannot also be used), it does make is much easier to use for complex data.

Select a single row by id:

var table = new DataTable('#myTable');
var row = table.row('#row-42');

Select multiple rows by id:

var table = new DataTable('#myTable');
var rows = table.rows( [ '#row-42', '#row-51' ] );

string

When the selector is given as a string, it is treated as a jQuery selector that operates on the tr elements in the table. For full information about the options available for jQuery selectors, please refer to the jQuery selector documentation.

Note that just like jQuery selector, is it possible to supply multiple selectors using comma separated notation (i.e. just separate by a comma) when the selector is provided as a string.

Select rows by class name:

var table = new DataTable('#myTable');
var rows = table.rows('.priority');

Select rows by two class name selectors:

var table = new DataTable('#myTable');
var rows = table.rows('.important, .intermediate');

node

tr DOM elements can be given as a row selector to select a row in the DataTabels API from that DOM element. This can be useful for getting data from a row, or performing other row based operations, when you have only the DOM node for reference, for example in an event handler.

Get the data for a row that was clicked upon:

var table = new DataTable('#myTable');

$('#example tbody').on( 'click', 'tr', function () {
  var rowData = table.row( this ).data();
  // ... do something with `rowData`
} );

Function

For complete control over which rows are selected, it is possible to provide a function with logic you've defined to perform the selection. That logic can be as simple or as complex as you wish, performing the selection by simply returning true if the row should be included in the selected results and false if not.

That can be particularly useful for finding rows based on the data contained in the rows, or based on properties of the nodes.

The function receives three parameters:

1. Row index - see row().index()
2. Row data - see row().data(). Note that this is the original data object for the row, not the rendered data if you are using columns.render
3. Row node - see row().node(). Note that this may be null if you are using deferRender.

The function is called once for every row that can be selected, based on the selector-modifier options, which also defines the order of the rows for the called function.

Get the data for all rows that have a first_name starting with A:

var table = new DataTable('#myTable');

var names = table
    .rows( function ( idx, data, node ) {
        return data.first_name.charAt(0) === 'A' ?
            true : false;
    } )
    .data();

jQuery

Very similar to the above node type (since a jQuery object is an array-like list of DOM nodes), a jQuery instance can be given as a row selector, with any nodes which are selected by jQuery and match those available in the table selected.

Get data from rows in a jQuery instance:

var rows = $('tr.immediate');
var table = new DataTable('#myTable');

var rowData = table.rows( rows ).data();

Use jQuery selectors to get the data in the fifth row of the table:

var rowData1 = table.rows( ':nth-child(5)' ).data();
var rowData2 = table.rows( ':eq(4)' ).data();

array

Any combination of the above options can be given as selector together, providing a method to select multiple rows, or to mix selector types, by simply providing the selector options you want in an array.

Get the data for two rows, based on id:

var table = new DataTable('#myTable');
var data = table.rows( ['#row-42', '#row-91'] ).data();

Mix row-selector types - id and class selector

var table = new DataTable('#myTable');
var data = table.rows( ['#row-42', '.important'] ).data();