Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/glittershark/reactable

Fast, flexible, and simple data tables in React
https://github.com/glittershark/reactable

Last synced: 7 days ago
JSON representation

Fast, flexible, and simple data tables in React

Awesome Lists containing this project

README 

        
# Reactable



[![Build Status](https://travis-ci.org/glittershark/reactable.svg?branch=master)](https://travis-ci.org/glittershark/reactable)

[![Code Climate](https://codeclimate.com/github/glittershark/reactable/badges/gpa.svg)](https://codeclimate.com/github/glittershark/reactable)



Fast, flexible, and simple data tables in React.



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/



This project is currently alpha-stage, which means the API may or may not be

unstable and there might be hidden bugs lurking around any corner. I'll try to

tag any releases with breaking changes, however, and the more people who use

this the faster we can get to 1.0!



**Note:** As of version 0.12.0 Reactable will only continue to support React

0.14 and higher.



## 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 Bower



```sh

bower install [--save] reactable

```



### 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 the latest version of React (0.14), which

can be downloaded [here][download]



[build-file]: https://github.com/glittershark/reactable/raw/master/build/reactable.js

[download]: http://facebook.github.io/react/downloads.html

[lib-folder]: https://github.com/glittershark/reactable/tree/master/lib



## Usage



The simplest example:



```jsx

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

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

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

  `` components as children (note the exclusion of a `` here),

  each of which should have a "column" property. The children of these ``

  components (either strings or React components themselves) will be used to

  render the table headers. For example:



```jsx

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 `` 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(

    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

var Table = Reactable.Table,

    Tr = Reactable.Tr,

    Td = Reactable.Td;



ReactDOM.render(

    

        

            

                


                   Some Text or Icon

                   Griffin Smith

                


            

            18

        

    ,

    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.