import { ArgTypes } from '@storybook/blocks';
import { Table } from './Table';

# Table

Used for displaying tabular data

## Sub-tables

Sub-tables are supported by adding `FieldType.nestedFrames` to the field that contains the nested data in your dataframe.

This nested fields values can contain an array of one or more dataframes. Each of these dataframes will be rendered as one unique sub-table.

For each dataframe and index in the nested field, the dataframe will be rendered as one or more sub-tables below the main dataframe row at that index.

### Unique rowId

In some cases it makes sense to persist the opened/closed state of the sub-tables. For example: with streaming queries where a user may manipulate the state while additional data is still loading. In such cases use `dataframe.meta.uniqueRowIdFields` property to specify which fields create unique row id and table will use it to persist the state across data changes.

## Custom dataframe properties

Each dataframe also supports using the following custom property under `dataframe.meta.custom`:

- **noHeader**: boolean - Hides that sub-tables header.

- @deprecated use `FieldType.nestedFrames` instead
  - **parentRowIndex**: number - The index of the parent row in the main dataframe (under the `data` prop of the Table component).

## Table rendering

Table component only works in conjunction with the applyFieldOverrides function from the @grafana/data package otherwise data will not render.

```javascript
import { DataFrame, applyFieldOverrides, GrafanaTheme2 } from '@grafana/data';
import { Table, useTheme2 } from '@grafana/ui';

const TableComponent = (dataFrame: DataFrame) => {
  const theme = useTheme2();
  const displayData = applyFieldOverrides({
    data: dataFrame,
    fieldConfig: {
      defaults: {
        custom: {
          align: 'auto',
          cellOptions: {
            type: 'gauge',
            mode: 'gradient',
          },
          inspect: false,
        },
        mappings: [],
        unit: 'locale',
      },
      overrides: [],
    },
    theme,
    replaceVariables: (value) => value,
  });

  return (
    <Table
      data={displayData}
      width={1000}
      height={400}
      columnMinWidth={50}
      footerOptions={{ show: true, reducer: ['sum'] }}
    />
  )
}
```

## Cell rendering

Cell rendering is controlled by table specific field config in the DataFrame passed as `data` prop. Each field can set its `field.config.custom` to be type `TableFieldOptions`. `TableFieldOptions` contain generic options to control some aspects of the cell and column rendering. They also contain `cellOptions` property which can be further used to control type of cell renderer that will be used. `cellOptions` subtypes:

- **TableAutoCellOptions**: Default cell renderer that does not have to be specified in the `field.config`. Just displays the value with appropriate formatting.
- **TableSparklineCellOptions**: Shows a small, time series chart inside the cell. The field values have to be an array of numbers or a DataFrame.
- **TableBarGaugeCellOptions**: Show a gauge inside the cell.
- **TableColoredBackgroundCellOptions**: Show the cell with a colored background.
- **TableColorTextCellOptions**: Make the text inside the cell colored.
- **TableImageCellOptions**: Show an image inside the cell.
- **TableJsonViewCellOptions**: Shows a formatted and indented JSON text.
- **TableCustomCellOptions**: Allows to specify a custom cell renderer as React function component.

## Usage

<ArgTypes of={Table} />
