# Reactable [![license](https://img.shields.io/github/license/abdulrahman-khankan/reactable.svg)](https://github.com/abdulrahman-khankan/reactable/blob/master/LICENSE) [![npm](https://img.shields.io/npm/v/reactable.svg)](https://www.npmjs.com/package/reactable) [![npm](https://img.shields.io/npm/dw/reactable.svg)](https://www.npmjs.com/package/reactable) [![npm](https://img.shields.io/npm/dt/reactable.svg)](https://www.npmjs.com/package/reactable) [![Build Status](https://travis-ci.org/abdulrahman-khankan/reactable.svg?branch=master)](https://travis-ci.org/abdulrahman-khankan/reactable) Fast, flexible, and simple data tables in React (up to v16). Reactable allows you to display tabular data client-side, and provides sorting, filtering, and pagination over that data. It uses the power of [React.js][react] to do all this very, very quickly, and provides an API that makes simple things easy, while trying to get out of your way as much as possible if you want to do something complicated or unconventional. [react]: http://facebook.github.io/react/ There might be hidden bugs lurking around any corner. I'll try to tag any releases with breaking changes. **Note**: As of version 1.0.0 ownership of npm reactable package has transferred and linked to this repo as previous owner is no longer maintaining the project. Old issues can be found [here](https://github.com/glittershark/reactable/issues). Feel free to submit new issues [here](https://github.com/abdulrahman-khankan/reactable/issues). ## Table of Contents - [Installation](#installation) - [Usage](#usage) - [Further Customization](#further-customization) - [Even More Customization](#even-more-customization) - [Additional node types](#additional-node-types) - [Customizing Columns](#customizing-columns) - [Preventing escaping of HTML](#preventing-escaping-of-html) - [Pagination](#pagination) - [Sorting](#sorting) - [Filtering](#filtering) - [Empty Data Sets](#empty-data-sets) - [Events](#events) ## Installation ### Using NPM ```sh npm install [--save] reactable ``` Or, you can just download the raw file [here][build-file]. That file can be used either as an AMD module, as a CommonJS module in Node, or, if neither are supported, will register the Reactable object as a property of the `window` object. Reactable also exposes a set of CommonJS modules for piece-by-piece use with Node, Webpack, Browserify, etc. These modules are located in the [`lib` folder at the root of this repositiory][lib-folder]. Keep in mind that Reactable depends on React, which can be downloaded [here][download] [build-file]: https://github.com/abdulrahman-khankan/reactable/raw/master/build/reactable.js [download]: http://facebook.github.io/react/downloads.html [lib-folder]: https://github.com/abdulrahman-khankan/reactable/tree/master/lib ## Usage The simplest example: ```jsx // ES6 // import { Table } from "reactable"; var Table = Reactable.Table; ReactDOM.render( , document.getElementById('table') ); ``` While pretty basic, this example demonstrates a couple things: - Columns in the data array can be in any order, and you can omit any you like - Regular React DOM attributes such as className will pass-through to the rendered `

` - Data values can be any type with a `toString()` method ### Further Customization You can also manually build up your rows using `Reactable.Tr` nested in a table, also using the `data` prop, but this time containing only one javascript object. This approach can be freely combined with the `data` property on the `

`, and is useful if you want to specify per-row attributes such as classes, like so: ```jsx // ES6 // import { Table, Tr } from "reactable"; var Table = Reactable.Table, Tr = Reactable.Tr; ReactDOM.render(

, document.getElementById('table') ); ``` ### Even More Customization If you want to customize the rendering of individual columns, you can go a level deeper by embedding a `Reactable.Td` inside your `Reactable.Tr`. These have the required `column` property, and an optional `value` property if you want to customize the data that's used for sorting and filtering - if the latter isn't specified, the data used will default to the `Td`'s children. Example: ```jsx // ES6 // import { Table, Tr, Td } from "reactable"; var Table = Reactable.Table, Tr = Reactable.Tr, Td = Reactable.Td; ReactDOM.render(

Griffin Smith	18
Lee Salminen	23
Developer	28

, document.getElementById('table') ); ``` ### Customizing Columns To override inferring the column list from the attributes of the passed `data` objects, you can either: - Pass a `columns` array property to the `` component, which can be either: - An array of strings, in which case only the given properties will be included as columns in the rendered table. - An array of objects, each of which must have a `key` and `label` property. The `key` property is the attribute of the row object from which to retrieve value, and the `label` is the text to render in the column header row. - Define a `` component as the **first child** of the `

`, with `` here), each of which should have a "column" property. The children of these `` for your table, via the `Reactable.Tfoot` class. Per the HTML spec, there can only be one `` per table and its only children should be React.DOM `` elements (**not** `` elements). ### Preventing escaping of HTML If you don't want to go all the way down the JSX rabbit hole to render individual cells as HTML, and you know your source data is safe, you can wrap strings in `Reactable.unsafe` to prevent their content from being escaped, like so: ```jsx var Table = Reactable.Table, unsafe = Reactable.unsafe; ReactDOM.render(

` components as children (note the exclusion of a `

` components (either strings or React components themselves) will be used to render the table headers. For example: ```jsx // ES6 // import { Table, Thead, Th, Tr, Td } from "reactable"; var Table = Reactable.Table, Thead = Reactable.Thead, Th = Reactable.Th, Tr = Reactable.Tr, Td = Reactable.Td; ReactDOM.render(

First Name, Last Name	Age, years
Griffin Smith	18
Lee Salminen	23
Developer	28

, document.getElementById('table') ); ``` In this example, the `position` column will **not** be rendered. ### Additional node types Reactable also supports specifying a `

Griffin Smith'), 'Github': unsafe('

') }, { 'Name': unsafe('Ian Zhang'), 'Github': unsafe('

') }, ]}/>, document.getElementById('table') ); ``` You can also pass in `unsafe` strings as column labels or in a `` ### Pagination You can also use pagination, by just specifying an `itemsPerPage` argument to the `

` component. Include an optional `pageButtonLimit` argument to customize the number of page buttons in the pagination, which defaults to 10. For example: ```jsx

``` You can also change the default text on the buttons by including the `previousPageLabel` and `nextPageLabel` props. ### Sorting To enable sorting on all columns, just specify `sortable={true}` on the `

` component. For further customization, ie disabling sort or using a custom sort function on a per-column basis, you can pass an array to `sortable`, which contains either string column names or column objects. We've pre-built some sort functions for you. - `CaseInsensitive` will sort strings alphabetically regardless of capitalization (e.g. Joe Smith === joe smith) - `Date` will sort dates using JavaScript's native Date parser (e.g. 4/20/2014 12:05 PM) - `Currency` will sort USD format (e.g. $1,000.00) - `Numeric` will parse integer-like strings as integers (e.g. "1") - `NumericInteger` will parse integer strings (use `Numeric` if you might have floats) To specify a custom sort function, use the following structure for the column object: ```jsx {column: 'Column Name', sortFunction: function(a, b){ return a > b ? 1 : -1; }} ``` You can also specify a default sort by passing in either a column name by itself, or an object with a column and a `direction` paramenter of either `asc` or `desc`. If no direction is specified, the default sort will be ascending. Example: ```jsx {column: 'Column Name', direction: 'asc' } ``` Combined example: ```jsx

``` In case you are constructing your table without the data attribute, and the cells contain some additional HTML elements, you can use the value property on the Td element to define the value to sort for. In the following example we define two TDs, where the first contains some additional markup. We tell the Td to take "Griffin Smith" as value for data handling (filter or sort). ```jsx // ES6 // import { Table, Tr, Td } from "reactable"; var Table = Reactable.Table, Tr = Reactable.Tr, Td = Reactable.Td; ReactDOM.render(

Some Text or Icon Griffin Smith

, document.getElementById('table') ); ``` There is also an boolean `defaultSortDescending` option to default the sorting of a column to descending when clicked: ```jsx ``` There is also a `filterBy()` function on the component itself which takes a single string and applies that as the filtered value. It can be used like so: ```jsx var table = ReactDOM.render(

, document.getElementById('table') ); table.filterBy('new'); ``` You can also pass in a `filterBy` prop to control the filtering outside of the `Table` component: ```jsx var table = ReactDOM.render(

, document.getElementById('table') ); ``` If you are using your own input field to control the `filterBy` prop, you can hide the build-in filter input field with the `hideFilterInput` prop: ```jsx var table = ReactDOM.render(

, document.getElementById('table') ); ``` These can be useful if you want to roll your own filtering input field outside of Reactable. You can also provide your own custom filtering functions: ```jsx

-1); } }, 'Tag' ]} /> ``` Your filter function must return a boolean. Refraining from specifying a custom filter function will default to case-insensitive filtering. ### Empty Data Sets If the table is initialized without any ``s or with an empty array for `data`, you can display text in the body of the table by passing a string for the optional `noDataText` prop: ```jsx var table = ReactDOM.render(

, document.getElementById('table') ); ``` ### Events You can pass functions to the following props of `` to provide event handlers. #### onSort Called when the sorting in the table changes. This handler will be passed an object that contains the column name that is being sorted by, and the direction it is being sorted: ```js { column: 'Name', direction: -1 } ``` #### onFilter Called every time the filtering changes. This handler will be passed a string containing the text that's being used for filtering. #### onPageChange Called every time the page changes. This handler will be passed a number representing the current page, zero based.

ag-grid vs rc-table vs react-data-grid vs reactable

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past