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. While offering a wide range of options to control the layout around the table, the basic operation of this option is quite simple: use the object parameter name to place a control and then the value to state what feature should be shown, and its configuration.

Let's start with the default:

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

You can see that at the four corners of the DataTable it will place a different feature. Two rows are defined - the top and bottom, with start and end used for each.

To replace a feature with a different one (e.g. the Buttons extension) simply set the value to match the feature needed. Equally, if you wish to remove a feature, set it to null. For example in the below we set the top row to contain only the Buttons extension (note also that the bottom row will take the default values automatically):

{
    topStart: 'buttons',
    topEnd: null
}

Positional names

As seen, the names of the parameters in the layout object tell DataTables where to place the feature. It is made up of three parts:

• top or bottom - to dictate if the feature appears above or below the table
• A number (optional) - allows multiple rows in the layout grid. If omitted, it appears next to the table.
• Start or End (optional) - if the feature should appear at the start or the end of the row. If omitted it will take up the entire width of the container.

If you think in regex, then the formal definition for this is (top|bottom)[0-9]*(Start|End)?.

Layout grid

The layout grid that DataTables creates for layout looks like this:

Keep in mind that each of the entries in the layout grid are option. Set the value to be null or undefined to have it not appear.

This example can be useful if you'd like to see what the grid layout looks like visually.

Values

Thus far, we've discussed only positioning of features, but now let's consider the values that define the features and their configuration. A feature is a control element that interacts with the DataTable in someway.

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 (example). The built in features are:
  • info - Table information summary
  • pageLength - Page length control
  • paging - User input control for paging
  • search - Search input box
  • div - A simple placeholder element
• 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 (example). 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.
• object - A plain object with a parameter named features for control of the id and class of the grid elements (since 2.1 - example). Please see the IDs and class names section below.
• jQuery - A jQuery instance containing a node to insert.
• node - A DOM element (example).
• function - A function that returns a DOM element or jQuery instance containing a node (example). 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 (example).
• null - Show nothing in this position

Consider the following example as two of the most common ways to configure the table's control features:

new DataTable('#example', {
    layout: {
        topStart: 'info',
        topEnd: {
            search: {
                placeholder: 'Search'
            }
        }
    }
});

• Line 3: will place the info information feature at the top left (lrt) of the table.
• Line 4-8: places the search input at the top right (ltr) with the search.placeholder option configured.

Further examples are available below, and also in the layout section of the examples.

IDs and class names

DataTables will automatically assign class names to the layout grid to be suitable for the styling framework that you are using, but it is also possible to specify your own IDs and class names for the elements created (since 2.1). For this we use the second object form that layout can accept - an object with a features array property.

The object with a features property lets you specify row id/class and cell id/class as well as feature. As a Typescript interface the object looks like:

interface {
/** Class to apply to the CELL in the layout grid */
className?: string;

/** Id to apply to the CELL in the layout grid */
id?: string;

/** Class to apply to the ROW in the layout grid */
rowClass?: string;

/** Id to apply to the ROW in the layout grid */
rowId?: string;

/** List of features to show in this cell */
features: Features[];
}

If we consider a single string layout - e.g. top: 'info' this is the same as:

top: {
    features: ['info']
}

Equally, if we have a feature which needs configuration, such as the search from the previous example, it can be written as:

topEnd: {
    features: {
        search: {
            placeholder: 'Search'
        }
    }
}

From there you will be able to see how you can then use the id, className and other properties to control the classes / ids used for the grid layout.

Please note that if you do use this form to control the classes names, it will replace the default class names - i.e. the class(es) you define are the only ones on that element.

See this example for a live demonstration of the use of these properties and techniques.

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
	}
});

// Sets to show paging feature below the table only
DataTable.defaults.layout = {
	topStart: null,
	topEnd: null,
	bottomStart: null,
	bottomEnd: null,
	bottom: 'paging'
};

new DataTable('#myTable');

// Remove the defaults
DataTable.defaults.layout = {
	topStart: null,
	topEnd: null,
	bottomStart: null,
	bottomEnd: null
};

new DataTable('#myTable', {
	top: ['pageLength', 'search'],
	bottom: ['info', 'paging']
});

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;
		}
	}
});