# Data Table

<!--single-column-->

DataTable is used to displays rows of structured data.

## Demos
<n-alert type="warning" title="Caveat" style="margin-bottom: 16px;">
  Every row data needs a unique key property, otherwise you should specify <n-text code>row-key</n-text>
</n-alert>

```demo
basic
border
size
filter-and-sorter
select
controlled-page
controlled-filter
controlled-sorter
fixed-header
fixed-header-column
ellipsis
render-header
custom-style
ajax-usage
```

## Props
|Name|Type|Default|Description|
|-|-|-|-|
|theme|`'light' \| 'dark' \| string`|`undefined`||
|data|`Array<Object>`|`[]`|Data to display.|
|columns|`Array<Column>`|required|Columns to display.|
|max-height|`number \| string`|`undefined`|The max-height of the table. If content height is larger than it, the header will be fixed at top|
|min-height|`number \| string`|`undefined`|The min-height of the table.|
|loading|`boolean`|`false`||
|scroll-x|`number \| string`|`undefined`|If columns are horizontal fixed, scroll-x need to be set|
|pagination|`false \| Object`|`false`|See [Pagination props](n-pagination#Props)|
|paging|`boolean`|`true`|If data-table do automatic paging. You may set it to `false` in async usage.|
|row-class-name|`string \| (rowData: Object, index : number) => string \| Object`|`null`||
|checked-row-keys|`Array<string \| number> \| null`|`null`|The keys of checked rows.|
|default-checked-row-keys|`Array<string \| number>`|`[]`||
|row-key|`(rowData: Object) => number \| string`|`null`|Generate the key of the row by row data (if you don't want to set the key)|
|bordered|`boolean`|`true`||
|single-line|`boolean`|`true`||
|single-column|`boolean`|`false`||
|size|`'small' \| 'medium' \| 'large'`|`'medium'`||
|on-update:filters|`(filters: { [string \| number]: Array<string \| number> \| string \| number }, initiatorColumn: Column)`||
|on-update:sorter|`(options: { columnKey: string \| number, sorter: 'default' \| function \| boolean, order: 'ascend' \| 'descend' \| false } \| null) => any`|`undefined`|If there won't be a active sorter after change, `options` will be `null`|
|on-update:page|`(page: number)`|`undefined`||
|on-update:page-size|`(pageSize: number) => any`|`undefined`||
|on-update:checked-row-keys|`(keys: Array<string \| number>) => any`|`undefined`||

## Methods
These methods can help you control table in an uncontrolled manner. However, it's not recommended to use them to implement some async operations. If async operations is needed, use table in a **controlled** manner.

|Name|Type|Description|
|-|-|-|
|filters|`(filters: { [string \| number]: Array<string \| number> \| string \| number }) => void`|Set the active filters of the table.|
|sort|`(columnKey: string \| null, order: 'ascend' \| 'descend' \| false) => void`|If columnKey set to `null`, it is the same as clearSorter.|
|page|`(page: number) => void`||
|clearFilters|`() => void`||
|clearSorter|`() => void`||


## Events
|Name|Parameters|Description|
|-|-|-|
|filters-change|`(filters: { [string \| number]: Array<string \| number> }, initiatorColumn: Column)`||
|sorter-change|`(data: { columnKey: string \| number, sorter: 'default' \| function \| boolean, order: 'ascend' \| 'descend' \| false } \| null)`|If there won't be a active sorter after change, sorter-change will emit `null`|
|page-change|`(page: number)`||
|page-size-change|`(pageSize: number)`||
|checked-row-keys-change|`(keys: Array<string \| number>)`||

## API
### Column Properties
|Name|Type|Default|Description|
|-|-|-|-|
|render|`(rowData: Object) => VNode \| Array<VNode>`|`null`|Render function of column row cell|
|type|`'default' \| 'selection'`|`default`||
|disabled|`(rowData: Object, index: number) => boolean`|`() => false`||
|align|`'left' \| 'right' \| 'center'`|`'left'`|Text align in column|
|ellipsis|`boolean`|`false`||
|className|`string`|`null`||
|title|`string \| (() => VNode \| Array<VNode>)`|`null`|Can be a render function|
|key|`string`||Unique key of this column, **required** when table's row-key is not set.|
|sorter|`boolean \| function \| 'default'`|`false`|The sorter of the column. If set `'default'`, it will use a basic builtin compare function. If set to `true`, it will only display sort icon on the column, which can be used in async status. Otherwise it works like `Array.sort`'s compare function.|
|defaultSortOrder|`'descend' \| 'ascend' \| false`|`false`|The default sort order of the table in uncontrolled manner|
|sortOrder|`'descend' \| 'ascend' \| false \| null`|`null`|The controlled sort order of the column. If it is not `null`, the table's sort status will be in controlled mode. If multiple columns' sortOrder is set, the first one will affect.|
|filter|`boolean \| (optionValue: string \| number, rowData: Object) => boolean \| 'default'`|`false`|The filter of the column. If set to `true`, it will only display filter button on the column, which can be used in async status.|
|filterMode|`'and' \| 'or'`|`'or'`||
|filterOptions|`Array<{ label: string, value: string \| number}>`|`[]`||
|filterOptionValues|`Array<string \| number> \| null`|`undefined`|The active filter option values in controlled manner. If not set, the filter of the column works in an uncontrolled manner. (works when there are multiple filters)|
|filterOptionValue|`string \| number \| null`|`undefined`|The active filter option value in controlled manner. If not set, the filter of the column works in an uncontrolled manner. (works when not using multiple filters)|
|defaultFilterOptionValues|`Array<string \| number>`|`[]`|The default active filter option values in uncontrolled manner. (works when there are multiple filters)|
|defaultFilterOptionValue|`string \| number`|`null`|The default active filter option value in uncontrolled manner. (works when not using multiple filters)|
|filterMultiple|`boolean`|`true`||
|fixed|`'left \| 'right' \| false`|`false`||
|width|`number \| string`|`null`|Width of the column, **required** when fixed|