# MUI-Datatables - Datatables for MUI (formerly Material-UI)
MUI-Datatables is a responsive datatables component built on [Material-UI](https://www.material-ui.com). It comes with features like filtering, [resizable columns](https://codesandbox.io/s/muidatatables-custom-toolbar-zomv5?file=/index.js), view/hide columns, [draggable columns](https://codesandbox.io/s/muidatatables-resize-columns-example-tnrkc?file=/index.js), search, export to CSV download, printing, selectable rows, expandable rows, pagination, and sorting. On top of the ability to customize styling on most views, there are three responsive modes "vertical", "standard", and "simple" for mobile/tablet devices.
Version 3 has been released! You can read about the [updates here](https://github.com/gregnb/mui-datatables/blob/master/docs/v2_to_v3_guide.md)!
# Table of contents
- [MUI-Datatables - Datatables for MUI (formerly Material-UI)](#mui-datatables---datatables-for-mui-formerly-material-ui)
- [Table of contents](#table-of-contents)
- [Install](#install)
- [Compatibility](#compatibility)
- [Demo](#demo)
- [Usage](#usage)
- [API](#api)
- [<MUIDataTable />](#muidatatable-)
- [Options:](#options)
- [Customize Columns](#customize-columns)
- [Column:](#column)
- [Column Options:](#column-options)
- [Plug-ins](#plug-ins)
- [Available Plug-ins:](#available-plug-ins)
- [Customize Styling](#customize-styling)
- [Custom Components](#custom-components)
- [Remote Data](#remote-data)
- [Localization](#localization)
- [Contributing](#contributing)
- [License](#license)
- [Thanks](#thanks)
## Install
`npm install mui-datatables --save`
If your project doesn't already use them, you need to install mui v5 and it's icon pack:
`npm --save install @mui/material @emotion/react @emotion/styled @mui/icons-material`
## Compatibility
| mui-datatables | material-ui | Required Dependencies |
|----------------|-------------|-----------------------------------------------------|
| ^2.0.0 | ^3.0.0 | `@material-ui/core`,`@material-ui/icons` |
| ^3.0.0 | ^4.10.0 | `@material-ui/core`,`@material-ui/icons` |
| ^3.8.0 | ^4.12.0 | `@material-ui/core`,`@material-ui/icons` |
| ^4.0.0 | ^5.9.3 | `@mui/material`,`@mui/icons-material` |
## Demo
Browse live demos of all examples in this repo in [here](https://codesandbox.io/s/github/gregnb/mui-datatables)!
## Usage
For a simple table:
```js
import MUIDataTable from "mui-datatables";
const columns = ["Name", "Company", "City", "State"];
const data = [
["Joe James", "Test Corp", "Yonkers", "NY"],
["John Walsh", "Test Corp", "Hartford", "CT"],
["Bob Herm", "Test Corp", "Tampa", "FL"],
["James Houston", "Test Corp", "Dallas", "TX"],
];
const options = {
filterType: 'checkbox',
};
```
Or customize columns:
```
…
```
## API
#### <MUIDataTable />
The component accepts the following props:
|Name|Type|Description
|:--:|:-----|:-----|
|**`title`**|array|Title used to caption table
|**`columns`**|array|Columns used to describe table. Must be either an array of simple strings or objects describing a column
|**`data`**|array|Data used to describe table. Must be either an array containing objects of key/value pairs with values that are strings or numbers, or arrays of strings or numbers (Ex: data: [{"Name": "Joe", "Job Title": "Plumber", "Age": 30}, {"Name": "Jane", "Job Title": "Electrician", "Age": 45}] or data: [["Joe", "Plumber", 30], ["Jane", "Electrician", 45]]). The **customBodyRender** and **customBodyRenderLite** options can be used to control the data display.
|**`options`**|object|Options used to describe table
|**`components`**|object|Custom components used to render the table
#### Options:
|Name|Type|Default|Description
|:--:|:-----|:--|:-----|
|**`caseSensitive `**|boolean|false|Enable/disable case sensitivity for search.
|**`confirmFilters`**|boolean|false|Works in conjunction with the **customFilterDialogFooter** option and makes it so filters have to be confirmed before being applied to the table. When this option is true, the customFilterDialogFooter callback will receive an applyFilters function which, when called, will apply the filters to the table. [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/serverside-filters/index.js)
|**`columnOrder`**|array||An array of numbers (column indices) indicating the order the columns should be displayed in. Defaults to the order provided by the Columns prop. This option is useful if you'd like certain columns to swap positions (see draggableColumns option).
|**`count`**|number||User provided override for total number of rows.
|**`customFilterDialogFooter `**|function||Add a custom footer to the filter dialog. `customFilterDialogFooter(curentFilterList: array, applyFilters: function) => React Component`
|**`customFooter`**|function||Render a custom table footer. `function(count, page, rowsPerPage, changeRowsPerPage, changePage, `[`textLabels: object`](https://github.com/gregnb/mui-datatables/blob/master/src/textLabels.js)`) => string`|` React Component` [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/customize-footer/index.js)
|**`customRowRender `**|function||Override default row rendering with custom function. `customRowRender(data, dataIndex, rowIndex) => React Component`
|**`customSearch `**|function||Override default search with custom function. `customSearch(searchQuery: string, currentRow: array, columns: array) => boolean`
|**`customSearchRender `**|function||Render a custom table search. `customSearchRender(searchText: string, handleSearch, hideSearch, options) => React Component`
|**`customSort`**|function||Override default sorting with custom function. If you just need to override the sorting for a particular column, see the sortCompare method in the [column options](https://github.com/gregnb/mui-datatables#column-options). `function(data: array, colIndex: number, order: string) => array` [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/customize-sorting/index.js)
|**`customTableBodyFooterRender`**|function||Render a footer under the table body but above the table's standard footer. This is useful for creating footers for individual columns. [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/customize-footer/index.js)
|**`customToolbar`**|function||Render a custom toolbar `function({displayData}) => React Component`
|**`customToolbarSelect`**|function||Render a custom selected rows toolbar. `function(selectedRows, displayData, setSelectedRows) => void`
|**`download`**|boolean or string|true|Show/hide download icon from toolbar. Possible values:
- true: Button is visible and clickable.
- false: Button is not visible.
- disabled: Button is visible, but not clickable.
|**`downloadOptions`**|object|see ->|An object of options to change the output of the CSV file:
- `filename`: string
- `separator`: string
- `filterOptions`: object
- `useDisplayedColumnsOnly`: boolean
- `useDisplayedRowsOnly`: boolean
Default Value:`{filename: 'tableDownload.csv', separator: ','}`
|**`draggableColumns`**|object|{}|An object of options describing how dragging columns should work. The options are:
- `enabled:boolean`: Indicates if draggable columns are enabled. Defaults to false.
- `transitionTime:number`: The time in milliseconds it takes for columns to swap positions. Defaults to 300.
To disable the dragging of a particular column, see the "draggable" option in the columns options. Dragging a column to a new position updates the columnOrder array and triggers the onColumnOrderChange callback.
|**`elevation`**|number|4|Shadow depth applied to Paper component.
|**`enableNestedDataAccess`**|string|""|If provided a non-empty string (ex: "."), it will use that value in the column's names to access nested data. For example, given a enableNestedDataAccess value of "." and a column name of "phone.cell", the column would use the value found in `phone:{cell:"555-5555"}`. Any amount of nesting will work. [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/data-as-objects/index.js) demonstrates the functionality.
|**`expandableRows`**|boolean|false|Enable/disable expandable rows. [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/expandable-rows/index.js)
|**`expandableRowsHeader`**|boolean|true|Show/hide the expand all/collapse all row header for expandable rows.
|**`expandableRowsOnClick`**|boolean|false|Enable/disable expand trigger when row is clicked. When False, only expand icon will trigger this action.
|**`filter`**|boolean or string|true|Show/hide filter icon from toolbar. Possible values:
- true: Button is visiable and clickable.
- false: Button is not visible.
- disabled: Button is visible, but not clickable.
|**`filterArrayFullMatch`**|boolean|true|For array values, default checks if all the filter values are included in the array. If false, checks if at least one of the filter values is in the array.
|**`filterType`**|string||Choice of filtering view. `enum('checkbox', 'dropdown', 'multiselect', 'textField', 'custom')`
|**`fixedHeader`**|boolean|true|Enable/disable a fixed header for the table [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/fixed-header/index.js)
|**`fixedSelectColumn`**|boolean|true|Enable/disable fixed select column. [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/fixed-header/index.js)
|**`isRowExpandable`**|function||Enable/disable expansion or collapse on certain expandable rows with custom function. Will be considered true if not provided. `function(dataIndex: number, expandedRows: object(lookup: {dataIndex: number}, data: arrayOfObjects: {index: number, dataIndex: number})) => boolean`.
|**`isRowSelectable`**|function||Enable/disable selection on certain rows with custom function. Returns true if not provided. `function(dataIndex: number, selectedRows: object(lookup: {dataindex: boolean}, data: arrayOfObjects: {index, dataIndex})) => boolean`.
|**`jumpToPage`**|boolean|false|When true, this option adds a dropdown to the table's footer that allows a user to navigate to a specific page. [Example](https://github.com/gregnb/mui-datatables/blob/master/examples/large-data-set/index.js)
|**`onCellClick`**|function||Callback function that triggers when a cell is clicked. `function(colData: any, cellMeta: { colIndex: number, rowIndex: number, dataIndex: number }) => void`
|**`onChangePage`**|function||Callback function that triggers when a page has changed. `function(currentPage: number) => void`
|**`onChangeRowsPerPage`**|function||Callback function that triggers when the number of rows per page has changed. `function(numberOfRows: number) => void`
|**`onColumnOrderChange`**|function||Callback function that triggers when a column has been dragged to a new location. `function(newColumnOrder:array, columnIndex:number, newPosition:number) => void`
|**`onColumnSortChange`**|function||Callback function that triggers when a column has been sorted. `function(changedColumn: string, direction: string) => void`
|**`onDownload`**|function||A callback function that triggers when the user downloads the CSV file. In the callback, you can control what is written to the CSV file. This method can be used to add the Excel specific BOM character (see this [example](https://github.com/gregnb/mui-datatables/pull/722#issuecomment-526346440)). `function(buildHead: (columns) => string, buildBody: (data) => string, columns, data) => string`. Return `false` to cancel download of file.