layout

Define and position the table control elements to appear on the page.

Description

The layout option provides the ability to control the items that surround and control the DataTable. Using an object where the parameter names provide positional information, with the corresponding values telling DataTables what content to show, it is easy to create a wide variety of layouts that suit your specific needs.

Positional names

The names of the parameters in the layout object tell DataTables where it should insert the content defined by the value. The name first gives the side of the table where the control should be placed (top or bottom), optionally followed by a number indicating the display order, and then optionally Start or End. If neither is provided and only the table side value is given, the control will stretch the full width of the table. The formal syntax for this, in regex, is (top|bottom)[0-9]*(Start|End)?.

Please see the diagram in the DOM Structure section below for an illustrated example of this naming.

Values

The values of the parameters in layout can be any of:

• string - A string that represents a feature provided by DataTables or a plug-in. The built in features are:
  • info - Table information summary
  • pageLength - Page length control
  • paging - User input control for paging
  • search - Search input box
• object - A plain object where the parameter keys are the feature to be used (see the strings above and any plug-ins) and the value is passed to the feature. This is normally an object with a list of options. Note that multiple features could be specified using a single object, but order is not guaranteed. Order will normally be important if you specify multiple controls in a single slot - in such cases, use an array of objects.
• jQuery - A jQuery instance containing a node to insert
• node - A DOM element
• function - A function that returns a DOM element or jQuery instance containing a node. The function will be passed in the DataTables settings object.
• object - A class instance that provides a node() method and should return the node to be inserted (DOM or jQuery). As with the function option above, this method will be passed to the DataTables settings object for the table.
• array - An array of any of the above options, providing the ability to show multiple items next to each other.
• null - Show nothing in this position

DOM Structure

DataTables will insert the items given into a grid (suitable for the styling framework you have selected) using the structure depicted below:

Any of the positions can be left out or set to null and they will not appear. For example you could only use topN and bottomN if you didn't want the table controls to be left or right aligned.

Type

This option can be given in the following type(s):

• object

Default

The default layout for DataTables is:

{
    topStart: 'pageLength',
    topEnd: 'search',
    bottomStart: 'info',
    bottomEnd: 'paging'
}

Please note that if you assign one of the features used in the default object to a different location, it will not automatically be removed from its original position. For example, to display the search feature in the topStart position only, you would need to use:

{
    topStart: 'search',
    topEnd: null
}

Examples

new DataTable('#myTable', {
	layout: {
		topStart: null
	}
});

new DataTable('#example', {
	layout: {
		topStart: {
			pageLength: {
				menu: [ 10, 25, 50, 100 ]
			}
		},
		topEnd: {
			search: {
				placeholder: 'Type search here'
			}
		},
		bottomEnd: {
			paging: {
				numbers: 3
			}
		}
	}
});

new DataTable('#example', {
	layout: {
		top2Start: 'pageLength',
		top2End: 'search',
		topStart: 'info',
		topEnd: 'paging',
		bottomStart: 'pageLength',
		bottomEnd: 'search',
		bottom2Start: 'info',
		bottom2End: 'paging'
	}
});

new DataTable('#example', {
	layout: {
		topStart: function () {
			let toolbar = document.createElement('div');
			toolbar.innerHTML = '<b>Custom tool bar! Text/images etc.</b>';

			return toolbar;
		}
	}
});