3.8.1 • Published 2 years ago

@nwiservices/mui-datatables v3.8.1

Weekly downloads
-
License
MIT
Repository
bitbucket
Last release
2 years ago

MUI-Datatables - Datatables for Material-UI

Build Status NPM Downloads Coverage Status npm version

MUI-Datatables is a responsive datatables component built on Material-UI. It comes with features like filtering, resizable columns, view/hide columns, draggable columns, 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!

Table of contents

Install

npm install mui-datatables --save

If your project doesn't already use them, you need to install @material-ui/core and @material-ui/icons as well.

Demo

Edit react-to-print

Browse live demos of all examples in this repo in here!

Usage

For a simple table:

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',
};

<MUIDataTable
  title={"Employee List"}
  data={data}
  columns={columns}
  options={options}
/>

Or customize columns:

import MUIDataTable from "mui-datatables";

const columns = [
 {
  name: "name",
  label: "Name",
  options: {
   filter: true,
   sort: true,
  }
 },
 {
  name: "company",
  label: "Company",
  options: {
   filter: true,
   sort: false,
  }
 },
 {
  name: "city",
  label: "City",
  options: {
   filter: true,
   sort: false,
  }
 },
 {
  name: "state",
  label: "State",
  options: {
   filter: true,
   sort: false,
  }
 },
];

const data = [
 { name: "Joe James", company: "Test Corp", city: "Yonkers", state: "NY" },
 { name: "John Walsh", company: "Test Corp", city: "Hartford", state: "CT" },
 { name: "Bob Herm", company: "Test Corp", city: "Tampa", state: "FL" },
 { name: "James Houston", company: "Test Corp", city: "Dallas", state: "TX" },
];

const options = {
  filterType: 'checkbox',
};

<MUIDataTable
  title={"Employee List"}
  data={data}
  columns={columns}
  options={options}
/>

API

<MUIDataTable />

The component accepts the following props:

NameTypeDescription
titlearrayTitle used to caption table
columnsarrayColumns used to describe table. Must be either an array of simple strings or objects describing a column
dataarrayData 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.
optionsobjectOptions used to describe table
componentsobjectCustom components used to render the table

Options:

NameTypeDefaultDescription
caseSensitivebooleanfalseEnable/disable case sensitivity for search.
confirmFiltersbooleanfalseWorks 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
columnOrderarrayAn 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).
countnumberUser provided override for total number of rows.
customFilterDialogFooterfunctionAdd a custom footer to the filter dialog. customFilterDialogFooter(curentFilterList: array, applyFilters: function) => React Component
customFooterfunctionRender a custom table footer. function(count, page, rowsPerPage, changeRowsPerPage, changePage,textLabels: object) => string|React Component Example
customRowRenderfunctionOverride default row rendering with custom function. customRowRender(data, dataIndex, rowIndex) => React Component
customSearchfunctionOverride default search with custom function. customSearch(searchQuery: string, currentRow: array, columns: array) => boolean
customSearchRenderfunctionRender a custom table search. customSearchRender(searchText: string, handleSearch, hideSearch, options) => React Component
customSortfunctionOverride 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. function(data: array, colIndex: number, order: string) => array Example
customTableBodyFooterRenderfunctionRender a footer under the table body but above the table's standard footer. This is useful for creating footers for individual columns. Example
customToolbarfunctionRender a custom toolbar function({displayData}) => React Component
customToolbarSelectfunctionRender a custom selected rows toolbar. function(selectedRows, displayData, setSelectedRows) => void
downloadboolean or stringtrueShow/hide download icon from toolbar. Possible values:true: Button is visiable and clickable.false: Button is not visible.disabled: Button is visible, but not clickable.
downloadOptionsobjectsee ->An object of options to change the output of the CSV file:filename: stringseparator: stringfilterOptions: objectuseDisplayedColumnsOnly: booleanuseDisplayedRowsOnly: booleanDefault Value:{filename: 'tableDownload.csv', separator: ','}
draggableColumnsobject{}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.
elevationnumber4Shadow depth applied to Paper component.
enableNestedDataAccessstring""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 demonstrates the functionality.
expandableRowsbooleanfalseEnable/disable expandable rows. Example
expandableRowsHeaderbooleantrueShow/hide the expand all/collapse all row header for expandable rows.
expandableRowsOnClickbooleanfalseEnable/disable expand trigger when row is clicked. When False, only expand icon will trigger this action.
filterboolean or stringtrueShow/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.
filterArrayFullMatchbooleantrueFor 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.
filterTypestringChoice of filtering view. enum('checkbox', 'dropdown', 'multiselect', 'textField', 'custom')
fixedHeaderbooleantrueEnable/disable a fixed header for the table Example
fixedSelectColumnbooleantrueEnable/disable fixed select column. Example
isRowExpandablefunctionEnable/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.
isRowSelectablefunctionEnable/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.
jumpToPagebooleanfalseWhen true, this option adds a dropdown to the table's footer that allows a user to navigate to a specific page. Example
onCellClickfunctionCallback function that triggers when a cell is clicked. function(colData: any, cellMeta: { colIndex: number, rowIndex: number, dataIndex: number }) => void
onChangePagefunctionCallback function that triggers when a page has changed. function(currentPage: number) => void
onChangeRowsPerPagefunctionCallback function that triggers when the number of rows per page has changed. function(numberOfRows: number) => void
onColumnOrderChangefunctionCallback function that triggers when a column has been dragged to a new location. function(newColumnOrder:array, columnIndex:number, newPosition:number) => void
onColumnSortChangefunctionCallback function that triggers when a column has been sorted. function(changedColumn: string, direction: string) => void
onDownloadfunctionA 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). function(buildHead: (columns) => string, buildBody: (data) => string, columns, data) => string. Return false to cancel download of file.
onFilterChangefunctionCallback function that triggers when filters have changed. function(changedColumn: string, filterList: array, type: enum('checkbox', 'dropdown', 'multiselect', 'textField', 'custom', 'chip', 'reset'), changedColumnIndex, displayData) => void
onFilterChipClosefunctionCallback function that is triggered when a user clicks the "X" on a filter chip. function(index : number, removedFilter : string, filterList : array) => void Example
onFilterConfirmfunctionCallback function that is triggered when a user presses the "confirm" button on the filter popover. This occurs only if you've set confirmFilters option to true. function(filterList: array) => void Example
onFilterDialogClosefunctionCallback function that triggers when the filter dialog closes. function() => void
onFilterDialogOpenfunctionCallback function that triggers when the filter dialog opens. function() => void
onRowClickfunctionCallback function that triggers when a row is clicked. function(rowData: string[], rowMeta: { dataIndex: number, rowIndex: number }) => void
onRowExpansionChangefunctionCallback function that triggers when row(s) are expanded/collapsed. function(currentRowsExpanded: array, allRowsExpanded: array, rowsExpanded: array) => void
onRowsDeletefunctionCallback function that triggers when row(s) are deleted. function(rowsDeleted: object(lookup: {[dataIndex]: boolean}, data: arrayOfObjects: {index: number, dataIndex: number}), newTableData) => void OR false (Returning false prevents row deletion.)
onRowSelectionChangefunctionCallback function that triggers when row(s) are selected/deselected. function(currentRowsSelected: array, allRowsSelected: array, rowsSelected: array) => void
onSearchChangefunctionCallback function that triggers when the search text value has changed. function(searchText: string) => void
onSearchClosefunctionCallback function that triggers when the searchbox closes. function() => void
onSearchOpenfunctionCallback function that triggers when the searchbox opens. function() => void
onTableChangefunctionCallback function that triggers when table state has changed. function(action: string, tableState: object) => void
onTableInitfunctionCallback function that triggers when table state has been initialized. function(action: string, tableState: object) => void
onViewColumnsChangefunctionCallback function that triggers when a column view has been changed. Previously known as onColumnViewChange. function(changedColumn: string, action: string) => void
pagenumberUser provided page for pagination.
paginationbooleantrueEnable/disable pagination.
printboolean or stringtrueShow/hide print icon from toolbar. Possible values:true: Button is visiable and clickable.false: Button is not visible.disabled: Button is visible, but not clickable.
renderExpandableRowfunctionRender expandable row. function(rowData, rowMeta) => React Component Example
resizableColumnsbooleanfalseEnable/disable resizable columns.
responsivestring'stacked'Enable/disable responsive table views. Options: "vertical" (default value): In smaller views the table cells will collapse such that the heading is to the left of the cell value."standard": Table will stay in the standard mode but make small changes to better fit the allocated space."simple": On very small devices the table rows will collapse into simple display.Example
rowHoverbooleantrueEnable/disable hover style over rows.
rowsExpandedarrayUser provided expanded rows.
rowsPerPagenumber10Number of rows allowed per page.
rowsPerPageOptionsarray10,15,100Options to provide in pagination for number of rows a user can select.
rowsSelectedarrayUser provided array of numbers (dataIndexes) which indicates the selected rows.
searchboolean or stringtrueShow/hide search icon from toolbar. Possible values:true: Button is visiable and clickable.false: Button is not visible.disabled: Button is visible, but not clickable.
searchPlaceholderstringSearch text placeholder. Example
searchPropsobject{}Props applied to the search text box. You can set method callbacks like onBlur, onKeyUp, etc, this way. Example
searchOpenbooleanfalseInitially displays search bar.
searchAlwaysOpenbooleanfalseAlways displays search bar, and hides search icon in toolbar.
searchTextstringSearch text for the table.
selectableRowsstring'multiple'Indicates if rows can be selected. Options are "multiple", "single", "none".
selectableRowsHeaderbooleantrueShow/hide the select all/deselect all checkbox header for selectable rows.
selectableRowsHideCheckboxesbooleanfalseHides the checkboxes that appear when selectableRows is set to "multiple" or "single". Can provide a more custom UX, especially when paired with selectableRowsOnClick.
selectableRowsOnClickbooleanfalseEnable/disable select toggle when row is clicked. When False, only checkbox will trigger this action.
selectToolbarPlacementstring'replace'Controls the visibility of the Select Toolbar, options are 'replace' (select toolbar replaces default toolbar when a row is selected), 'above' (select toolbar will appear above default toolbar when a row is selected) and 'none' (select toolbar will never appear)
serverSidebooleanfalseEnable remote data source.
setFilterChipPropsfunctionIs called for each filter chip and allows you to place custom props on a filter chip. function(colIndex: number, colName: string, filterValue: string) => object Example
setRowPropsfunctionIs called for each row and allows you to return custom props for this row based on its data. function(row: array, dataIndex: number, rowIndex: number) => object Example
setTablePropsfunctionIs called for the table and allows you to return custom props for the table based on its data. function() => object Example
sortbooleantrueEnable/disable sort on all columns.
sortFilterListbooleantrueEnable/disable alphanumeric sorting of filter lists.
sortOrderobject{}Sets the column to sort by and its sort direction. To remove/reset sorting, input in an empty object. The object options are the column name and the direction: name: string, direction: enum('asc', 'desc') Example
tableIdstringauto generatedA string that is used internally for identifying the table. It's auto-generated, however, if you need it set to a custom value (ex: server-side rendering), you can set it via this property.
tableBodyHeightstring'auto'CSS string for the height of the table (ex: '500px', '100%', 'auto').
tableBodyMaxHeightstringCSS string for the height of the table (ex: '500px', '100%', 'auto').
textLabelsobjectUser provided labels to localize text.
viewColumnsboolean or stringtrueShow/hide viewColumns icon from toolbar. Possible values:true: Button is visiable and clickable.false: Button is not visible.disabled: Button is visible, but not clickable.

Customize Columns

On each column object, you have the ability to customize columns to your liking with the 'options' property. Example:

const columns = [
 {
  name: "Name",
  options: {
   filter: true,
   sort: false
  }
 },
 ...
];

Column:

NameTypeDescription
namestringName of column (This field is required)
labelstringColumn Header Name override
optionsobjectOptions for customizing column

Column Options:

NameTypeDefaultDescription
customBodyRenderfunctionFunction that returns a string or React component. Used to display data within all table cells of a given column. The value returned from this function will be used for filtering in the filter dialog. If this isn't need, you may want to consider customBodyRenderLite instead. function(value, tableMeta, updateValue) => string|React Component Example
customBodyRenderLitefunctionFunction that returns a string or React component. Used to display data within all table cells of a given column. This method performs better than customBodyRender but has the following caveats: The value returned from this function is not used for filtering, so the filter dialog will use the raw data from the data array.This method only gives you the dataIndex and rowIndex, leaving you to lookup the column value.function(dataIndex, rowIndex) => string|React Component Example
customHeadLabelRenderfunctionFunction that returns a string or React component. Used for creating a custom header to a column. This method only affects the display in the table's header, other areas of the table (such as the View Columns popover), will use the column's label. function(columnMeta : object) => string|React Component