## File: README.md

# ngx-datatable

[](https://gitter.im/swimlane/ngx-datatable?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://codeclimate.com/github/swimlane/ngx-datatable)
[](https://codeclimate.com/github/swimlane/ngx-datatable/coverage)
[](https://badge.fury.io/js/%40swimlane%2Fngx-datatable)
[](https://npmjs.org/@swimlane/ngx-datatable)

`ngx-datatable` is an Angular component for presenting large and complex data. It has all the features you would expect from any other table but in a light package with _no external dependencies_. The table was designed to be extremely flexible and light; it doesn't make any assumptions about your data or how you: filter, sort or page it.

Check out the [documentation](https://swimlane.gitbook.io/ngx-datatable/) & [demos](http://swimlane.github.io/ngx-datatable/) for more information!

See the [changelog](https://github.com/swimlane/ngx-datatable/blob/master/docs/changelog.md) for recent changes.

## Features

- Handle large data sets ( Virtual DOM )
- Expressive Header and Cell Templates
- Horizontal & Vertical Scrolling
- Column Reordering & Resizing
- Client/Server side Pagination & Sorting
- Intelligent Column Width Algorithms ( Force-fill & Flex-grow )
- Integrated Pager
- Cell & Row Selection ( Single, Multi, Keyboard, Checkbox )
- Fixed AND Fluid height
- Left and Right Column Pinning
- Row Detail View
- Decoupled theme'ing with included Google Material theme
- Light codebase / No external dependencies
- AoT Compilation Support
- Universal Support

## Installation

To use ngx-datatable in your project install it via [npm](https://www.npmjs.com/package/@swimlane/ngx-datatable):

```
npm i @swimlane/ngx-datatable --save
```

## Building

Run `yarn build` to build the project. The build artifacts will be stored in the `dist/` directory.

## Running tests

- Run `yarn test` to execute the linter, prettier check, unit and end-to-end tests.

## Release

- Checkout master (`git checkout master`)
- Pull master (`git pull`)
- Refresh node modules (`yarn install --frozen-lockfile`)
- Run tests (`yarn test`)
- Examine log to determine next version (X.Y.Z)
- Run `git checkout -b release/X.Y.Z`
- Update version in `projects/swimlane/ngx-datatable/package.json`.
- Update changelog in `docs/CHANGELOG.md`
- Run `yarn package` to build the package
- Run `git commit -am "(release): X.Y.Z"`
- Run `git tag X.Y.Z`
- Run `git push origin HEAD --tags`
- Run `yarn publish`
- Submit PR

## Credits

`ngx-datatable` is a [Swimlane](http://swimlane.com) open-source project; we believe in giving back to the open-source community by sharing some of the projects we build for our application. Swimlane is an automated cyber security operations and incident response platform that enables cyber security teams to leverage threat intelligence, speed up incident response and automate security operations.

---

## File: docs/api/table/inputs.md

# Table Inputs

## `columnMode`

Method used for setting column widths

| Value      | Description                 | Default |
| ---------- | --------------------------- | ------- |
| `standard` | Distributes based on widths | x       |
| `flex`     | Uses flex-grow API          |         |
| `force`    | Distributes proportionally  |         |

## `columns`

Array of columns to display

## `count`

Total count of all rows. Default value: `0`

## `cssClasses`

Custom CSS classes that can be defined to override the icons classes for up/down in sorts and
previous/next in the pager. Defaults:

```
sortAscending: 'datatable-icon-down',
sortDescending: 'datatable-icon-up',
pagerLeftArrow: 'datatable-icon-left',
pagerRightArrow: 'datatable-icon-right',
pagerPrevious: 'datatable-icon-prev',
pagerNext: 'datatable-icon-skip'
```

## `externalPaging`

Use external paging instead of client-side paging. Default value: `false`

## `externalSorting`

Use external sorting instead of client-side sorting. Default value: `false`

## `footerHeight`

The height of the footer in pixels. Pass a `falsey` for no footer. Default value: `0`

## `headerHeight`

The height of the header in pixels. Pass a falsy value for no header. Default value: `30`

## `messages`

Static messages in the table you can override for localization.

```
{
  // Message to show when array is presented
  // but contains no values
  emptyMessage: 'No data to display',

  // Footer total message
  totalMessage: 'total',

  // Footer selected message
  selectedMessage: 'selected',

  // Pager screen reader message for the first page button
  ariaFirstPageMessage: 'go to first page',

  // Pager screen reader message for the previous page button
  ariaPreviousPageMessage: 'go to previous page',

  // Pager screen reader message for the n-th page button.
  // It will be rendered as: `{{ariaPageNMessage}} {{n}}`.
  ariaPageNMessage: 'page',

  // Pager screen reader message for the next page button
  ariaNextPageMessage: 'go to next page',

  // Pager screen reader message for the last page button
  ariaLastPageMessage: 'go to last page'
}
```

## `limit`

Page size to show. Default value: `undefined`

## `loadingIndicator`

Show the linear loading bar. Default value: `false`

## `offset`

Current offset ( page - 1 ) shown. Default value: `0`

## `reorderable`

Column re-ordering enabled/disabled. Default value: `true`

## `swapColumns`

Swap columns on re-order columns or move them. Default value: `true`

## `rowHeight`: `Function|number|undefined`

The height of the row.

When virtual scrolling is not in use, you can pass `undefined` for fluid heights.

If using virtual scrolling, you must pass a function or a number to calculate
the heights.

Using a function, you can set the height of individual rows:

```
(row) => {
  // set default
  if (!row) return 50;

  // return my height
  return row.height;
}
```

## `rowIdentity`

Function for uniquely identifying a row, used to track and compare when displaying and selecting rows. Example:

```
(row) => {
  return row.guid;
}
```

## `rows`

Array of rows to display.

## `scrollbarH`

Use horizontal scrollbar. Default value: `false`

## `scrollbarV`

Use vertical scrollbar for fixed height vs fluid. This is necessary for virtual scrolling. Default value: `false`

## `selectCheck`

A boolean or function you can use to check whether you want
to select a particular row based on a criteria. Example:

```
(row, column, value) => {
  return value !== 'Ethel Price';
}
```

## `displayCheck`

Function to determine whether to show a checkbox for a row. Example:

```
(row, column, value) => {
  return row.name !== 'Ethel Price';
}
```

## `selected`

List of row objects that should be represented as selected in the grid. Rows are compared using
object equality. For custom comparisons, use the `selectCheck` function.

Default value: `[]`

## `selectionType`

Row selection mode

| Value          | Description                                           | Default |
| :------------- | :---------------------------------------------------- | ------- | ----------------------- | --- |
| `undefined     | false                                                 | null`   | Rows cannot be selected | x   |
| `"single"`     | One row can be selected at a time                     |         |
| `"cell"`       | One cell can be selected at a time                    |         |
| `"multi"`      | Multiple rows can be selected using Ctrl or Shift key |         |
| `"multiClick"` | Multiple rows can be selected by clicking             |         |
| `"checkbox"`   | Multiple rows can be selected using checkboxes        |         |

## `sorts`

Ordered array of objects used to determine sorting by column. Objects contain the column name, `prop`, and sorting direction, `dir`. Default value: `[]`. Example:

```javascript
[
  {
    prop: 'name',
    dir: 'desc'
  },
  {
    prop: 'age',
    dir: 'asc'
  }
];
```

## `sortType`

Sorting mode, whether `"single"` or `"multi"`. In `"single"` mode, clicking on a column name
will reset the existing sorting before sorting by the new selection. In multi selection mode,
additional clicks on column names will add sorting using multiple columns.

Default value: `"single"`

## `trackByProp`

A property on the row object that uniquely identifies the row. Example: `"name"`

## `rowClass`

Function used to populate a row's CSS classes. The function will take a row and
return a string or object, as shown below:

```
(row) => {
  return {
    'old': row.age > 50,
    'young': row.age <= 50,
    'woman': row.gender === 'female',
    'man': row.gender === 'male'
  }
}
```

## `virtualization`

Use virtual scrolling. Default: `true`

---

## File: docs/api/table/outputs.md

# Table Outputs

All outputs are Angular `EventEmitter`ers.

### `activate`

A cell or row was focused via keyboard or mouse click.

```
{
  type: 'keydown'|'click'|'dblclick'
  event
  row
  column
  value
  cellElement
  rowElement
}
```

### `page`

The table was paged either triggered by the pager or the body scroll.

```
{
  count
  pageSize
  limit
  offset
}
```

### `reorder`

Columns were re-ordered.

```
{
  column
  newValue
  prevValue
}
```

### `resize`

Column was resized.

```
{
  column
  newValue
}
```

### `tableContextmenu`

The context menu was invoked on the table.

```
{
  event,
  type,
  content
}
```

### `scroll`

Body was scrolled typically in a `scrollbarV:true` scenario.

```
{
  offsetX
  offsetY
}
```

### `select`

A cell or row was selected.

```
{
  selected
}
```

### `sort`

Column sort was invoked.

```
{
  sorts
  column
  prevValue
  newValue
}
```

---

## File: docs/api/row/row-def.md

# Custom row wrapper

Use to pre-apply directives at row level.

### `rowDef`

Directive to be applied on `ng-template`.

### `datatable-row-def`

Component to be used as content of `ng-template`.
Apply your custom row level directive/class on this component. Example:

**Template**

```html
<ng-template rowDef>
  <datatable-row-def applyYourCustomDirectiveHereForRow />
</ng-template>
```

---

## File: docs/api/detail/inputs.md

# Row Detail Options

### `template`: `TemplateRef`

Template to use in the detail row. Example:

```
<ng-template let-row="row">
  
    **Address**
    {{row.address.city}}, {{row.address.state}}
  
</ng-template>
```

### `rowHeight`: `Number|Function`

Height of the detail row.

**Template**

```html
<ngx-datatable-row-detail [rowHeight]="getHeight" #myDetailRow (toggle)="onDetailToggle($event)">
  <ng-template let-row="row" ngx-datatable-row-detail-template>
    **Address**
    {{row.address.city}}, {{row.address.state}}
  </ng-template>
</ngx-datatable-row-detail>
```

**Typescript**

```javascript
getHeight(row: any, index: number): number {
  return row.someHeight;
}
```

---

## File: docs/api/detail/methods.md

## Row Detail Methods

### `collapseAllRows()`

Collapse all row details when using row detail templates.

### `expandAllRows()`

Expand all row details when using row detail templates.

### `toggleExpandRow(row)`

Toggle expand/collapse a row detail when using row detail templates.

---

## File: docs/api/detail/outputs.md

# Row Detail Outputs

All outputs are Angular `EventEmitter`ers.

### `toggle`

Row detail row was toggled.

```
{
  type: 'all' || 'row'
  value: boolean || row object
}
```

---

## File: docs/api/column/inputs.md

# Table Column Options

### `name`: `string`

Column label. If none specified, it will use the prop value and decamelize it.

### `prop`: `string`

The property to bind the row values to. If `undefined`, it will camelcase the name value.

### `flexGrow`: `number`

The grow factor relative to other columns. Same as the [flex-grow API](https://www.w3.org/TR/css3-flexbox/).
It will any available extra width and distribute it proportionally according to all columns' flexGrow values. Default value: `0`

### `minWidth`: `number`

Minimum width of the column in pixels. Default value: `100`

### `maxWidth`: `number`

Maximum width of the column in pixels. Default value: `undefined`

### `width`: `number`

The width of the column by default in pixels. Default value: `150`

### `resizeable`: `boolean`

The column can be resized manually by the user. Default value: `true`

### `comparator`

Custom sort comparator, used to apply custom sorting via client-side.
Function receives five parameters, namely values and rows of items to be sorted as well as direction of the sort ('asc'|'desc'):

```
(valueA, valueB, rowA, rowB, sortDirection) => -1|0|1
```

NOTE: Compare can be a standard JS comparison function (a,b) => -1|0|1 as additional parameters are silently ignored.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) for more info.

### `sortable`: `boolean`

Sorting of the row values by this column. Default value: `true`

### `draggable`: `boolean`

The column can be dragged to re-order. Default value: `true`

### `canAutoResize`: `boolean`

Whether the column can automatically resize to fill extra space. Default value: `true`

### `cellTemplate`: `TemplateRef`

Angular TemplateRef allowing you to author custom body cell templates

### `headerTemplate`: `TemplateRef`

Angular TemplateRef allowing you to author custom header cell templates

### `checkboxable`: `boolean`

Indicates whether the column should show a checkbox component for selection. Only
applicable when the selection mode is `checkbox`.

### `headerCheckboxable`: `boolean`

Indicates whether the column should show a checkbox component in the header cell.
Only applicable when the selection mode is `checkbox`.

### `headerClass`: `string|Function`

Header CSS classes to apply to the header cell

### `cellClass`: `string|Function`

Cell classes to apply to the body cell

### `frozenLeft`: `boolean`

Determines if the column is frozen to the left. Default value: `false`

### `frozenRight`: `boolean`

Determines if the column is frozen to the right. Default value: `false`

### `pipe`: `PipeTransform`

Custom pipe transforms. Default value: `undefined`