Nitrogen Peroxide Monoxide

    @sb-konzept/mui-datatables

    2.3.0 • Public • Published

    MUI-Datatables - Datatables for Material-UI

    Build Status NPM Downloads Coverage Status dependencies Status npm version

    MUI-Datatables is a data tables component built on Material-UI. It comes with features like filtering, resizable + view/hide 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 two responsive modes "stacked" and "scroll" for mobile/tablet devices.

    Install

    npm install mui-datatables --save

    Demo

    Edit react-to-print

    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:

    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 an array containing objects. (Arrays containing just strings or numbers also supported)
    options object Options used to describe table

    Options:

    Name Type Default Description
    page number User provided starting page for pagination
    count number User provided override for total number of rows
    serverSide boolean false Enable remote data source
    rowsSelected array User provided selected rows
    filterType string Choice of filtering view. enum('checkbox', 'dropdown', 'multiselect', 'textField')
    textLabels object User provided labels to localize text
    pagination boolean true Enable/disable pagination
    selectableRows string 'multiple' Numbers of rows that can be selected. Options are "multiple", "single", "none".
    isRowSelectable function Enable/disable selection on certain rows with custom function. Returns true if not provided. function(dataIndex) => bool
    resizableColumns boolean false Enable/disable resizable columns
    expandableRows boolean false Enable/disable expandable rows
    renderExpandableRow function Render expandable row. function(rowData, rowMeta) => React Component
    customToolbar function Render a custom toolbar
    customToolbarSelect function Render a custom selected rows toolbar. function(selectedRows, displayData, setSelectedRows) => void
    customFooter function Render a custom table footer. function(count, page, rowsPerPage, changeRowsPerPage, changePage) => string| React Component
    customRowRender function Override default row rendering with custom function. customRowRender(data, dataIndex, rowIndex) => React Component
    customSort function Override default sorting with custom function. function(data: array, colIndex: number, order: string) => array
    customSearch function Override default search with custom function. customSearch(searchQuery: string, currentRow: array, columns: array) => boolean
    elevation number 4 Shadow depth applied to Paper component
    caseSensitive boolean false Enable/disable case sensitivity for search
    responsive string 'stacked' Enable/disable responsive table views. Options: 'stacked', 'scroll'
    rowsPerPage number 10 Number of rows allowed per page
    rowsPerPageOptions array [10,15,20] Options to provide in pagination for number of rows a user can select
    rowHover boolean true Enable/disable hover style over rows
    fixedHeader boolean true Enable/disable fixed header columns
    sortFilterList boolean true Enable/disable alphanumeric sorting of filter lists
    sort boolean true Enable/disable sort on all columns
    filter boolean true Show/hide filter icon from toolbar
    search boolean true Show/hide search icon from toolbar
    searchText string Initial search text
    print boolean true Show/hide print icon from toolbar
    download boolean true Show/hide download icon from toolbar
    downloadOptions object Options to change the output of the CSV file. Default options: {filename: 'tableDownload.csv', separator: ','}
    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. function(buildHead: (columns) => string, buildBody: (data) => string, columns, data) => string
    viewColumns boolean true Show/hide viewColumns icon from toolbar
    onRowsSelect function Callback function that triggers when row(s) are selected. function(currentRowsSelected: array, allRowsSelected: array) => void
    onRowsDelete function Callback function that triggers when row(s) are deleted. function(rowsDeleted: object(lookup: {dataindex: boolean}, data: arrayOfObjects: {index, dataIndex})) => void OR false (Returning false prevents row deletion.)
    onRowClick function Callback function that triggers when a row is clicked. function(rowData: string[], rowMeta: { dataIndex: number, rowIndex: number }) => void
    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
    onSearchChange function Callback function that triggers when the search text value has changed. function(searchText: string) => void
    onSearchOpen function Callback function that triggers when the searchbox opens. function() => void
    onFilterChange function Callback function that triggers when filters have changed. function(changedColumn: string, filterList: array) => void
    onColumnSortChange function Callback function that triggers when a column has been sorted. function(changedColumn: string, direction: string) => void
    onColumnViewChange function Callback function that triggers when a column view has been changed. function(changedColumn: string, action: string) => void
    onTableChange function Callback function that triggers when table state has changed. function(action: string, tableState: object) => void
    setRowProps function Is called for each row and allows to return custom props for this row based on its data. function(row: array, dataIndex: number) => object

    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:

    Name Type Description
    name string Name of column (This field is required)
    label string Column Header Name override
    options object Options for customizing column

    Column Options:

    Name Type Default Description
    display string 'true' Display column in table. enum('true', 'false', 'excluded')
    empty boolean false This denotes whether the column has data or not (for use with intentionally empty columns)
    viewColumns boolean true Allow user to toggle column visibility through 'View Column' list
    filterList array Filter value list Example
    filterOptions array Filter options Example
    customFilterListRender function Function that returns a string used as the chip label. function(value) => string Example
    filter boolean true Display column in filter list
    filterType string 'dropdown' Choice of filtering view. Takes priority over global filterType option.enum('checkbox', 'dropdown', 'multiselect', 'textField').
    sort boolean true Enable/disable sorting on column
    searchable boolean true Exclude/include column from search results
    sortDirection string Set default sort order enum('asc', 'desc')
    print boolean true Display column when printing
    download boolean true Display column in CSV download file
    hint string Display hint icon with string as tooltip on hover.
    customHeadRender function Function that returns a string or React component. Used as display for column header. function(columnMeta, handleToggleColumn) => string| React Component
    customBodyRender function Function that returns a string or React component. Used as display data within all table cells of a given column. function(value, tableMeta, updateValue) => string| React Component Example
    setCellProps function Is called for each cell and allows to return custom props for this cell based on its data. function(cellValue: string, rowIndex: number, columnIndex: number) => object

    customHeadRender is called with these arguments:

    function(columnMeta: {
      customHeadRender: func,
      display: enum('true', 'false', 'excluded'),
      filter: bool,
      sort: bool,
      sortDirection: bool,
      download: bool,
      empty: bool,
      index: number,
      label: string,
      name: string,
      print: bool,
      searchable: bool,
      viewColumns: bool
    }, handleToggleColumn: function(columnIndex))

    customBodyRender is called with these arguments:

    function(value: any, tableMeta: {
      rowIndex: number,
      columnIndex: number,
      columnData: array, // Columns Options object
      rowData: array, // Full row data
      tableData: array, Full table data
      tableState: {
        announceText: null|string,
        page: number,
        rowsPerPage: number,
        filterList: array,
        selectedRows: {
          data: array,
          lookup: object,
        },
        showResponsive: boolean,
        searchText: null|string,
      },
    }, updateValue: function)

    Customize Styling

    Using Material-UI theme overrides will allow you to customize styling to your liking. First, determine which component you would want to target and then lookup the override classname. Let's start with a simple example where we will change the background color of a body cell to be red:

    import React from "react";
    import MUIDataTable from "mui-datatables";
    import { createMuiTheme, MuiThemeProvider } from '@material-ui/core/styles';
    
    class BodyCellExample extends React.Component {
    
      getMuiTheme = () => createMuiTheme({
        overrides: {
          MUIDataTableBodyCell: {
            root: {
              backgroundColor: "#FF0000"
            }
          }
        }
      })
    
      render() {
    
        return (
          <MuiThemeProvider theme={this.getMuiTheme()}>
            <MUIDataTable title={"ACME Employee list"} data={data} columns={columns} options={options} />
          </MuiThemeProvider>
        );
    
      }
    }

    Remote Data

    If you are looking to work with remote data sets or handle pagination, filtering, and sorting on a remote server you can do that with the following options:

    const options = {
      serverSide: true,
      onTableChange: (action, tableState) => {
        this.xhrRequest('my.api.com/tableData', result => {
          this.setState({ data: result });
        });
      }
    };

    To see an example Click Here

    Localization

    This package decided that the cost of bringing in another library to perform localizations would be too expensive. Instead the ability to override all text labels (which aren't many) is offered through the options property textLabels. The available strings:

    const options = {
      ...
      textLabels: {
        body: {
          noMatch: "Sorry, no matching records found",
          toolTip: "Sort",
        },
        pagination: {
          next: "Next Page",
          previous: "Previous Page",
          rowsPerPage: "Rows per page:",
          displayRows: "of",
        },
        toolbar: {
          search: "Search",
          downloadCsv: "Download CSV",
          print: "Print",
          viewColumns: "View Columns",
          filterTable: "Filter Table",
        },
        filter: {
          all: "All",
          title: "FILTERS",
          reset: "RESET",
        },
        viewColumns: {
          title: "Show Columns",
          titleAria: "Show/Hide Table Columns",
        },
        selectedRows: {
          text: "row(s) selected",
          delete: "Delete",
          deleteAria: "Delete Selected Rows",
        },
      }
      ...
    }

    Contributing

    Thanks for taking an interest in the library and the github community!

    The following commands should get you started:

    npm i
    npm run dev

    open http://localhost:5050/ in browser

    After you make your changes locally, you can run the test suite with npm test.

    License

    The files included in this repository are licensed under the MIT license.

    Thanks

    Thank you to BrowserStack for providing the infrastructure that allows us to test in real browsers.

    Install

    npm i @sb-konzept/mui-datatables

    DownloadsWeekly Downloads

    0

    Version

    2.3.0

    License

    MIT

    Unpacked Size

    239 kB

    Total Files

    6

    Last publish

    Collaborators

    • prio