> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supaboard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Format and organize a table

> Make detailed data easier to read with sorting, column formatting, grouping, and interaction controls.

The Table widget displays query results as a structured grid — rows and columns with full control over how each column looks, sorts, and highlights values.

## Before you begin

Add a table using the [dashboard editor](/dashboards/how-to/edit-a-dashboard) or reuse a result from the Analyst or Query Bench. You need editing access to save table settings.

## Open table settings

1. Choose **More options → Edit manually** on the dashboard.
2. Open the widget's **Table Settings** control.
3. Use **Settings** for the title, default sorting, and overall style; **Schema** for individual columns; and **Group**, **Pivot**, or **Click Behaviour** where available.
4. Review the preview, select **Save Changes**, then save the dashboard edits.

## Reading the data

Each row in the table corresponds to one row returned by the underlying query. Column headers are the field names from your query — you can rename them inside the widget without changing the query itself.

The table paginates automatically for large result sets. The total row count is shown in the widget footer.

**Null values** mean data is missing. Do not interpret them as zero. Check the underlying query if the distinction matters to your analysis.

**Numbers, dates, and text** are all displayed as returned by the database. Use [column controls](#column-controls) to add prefixes, suffixes, or formatting on top of the raw values.

## Sorting and filtering

Open the widget settings to set a **default sort**:

| Setting | Description |
| - | - |
| **Sort column** | The column to sort by when the widget first loads |
| **Sort direction** | `Ascending` or `Descending` |

Viewers can click any column header to sort interactively — this overrides the default sort for their session without changing the saved configuration.

**Filter data** lets you apply a persistent filter condition to the query results (e.g. show only rows where `status = "active"`). This filter is applied before the table renders and is not visible to viewers as a control.

## Column controls

Open **Schema** in the table settings and expand the column you want to configure. Column controls and available formats depend on its data type.

| Option | Description |
| - | - |
| **Rename** | Change the display label shown in the header |
| **Width** | Set a fixed pixel width for the column |
| **Prefix** | Text prepended to every value in the column (e.g. `$`, `€`) |
| **Suffix** | Text appended to every value (e.g. `%`, `ms`, `units`) |
| **Show header icon** | Display a small icon in the column header |

Prefix and suffix are purely visual — they do not change the underlying value used in sorts or calculations.

## Conditional formatting

Conditional formatting lets you apply styles to individual cells based on their value. Open the column's conditional-formatting control from the table settings or its header menu.

### Single color rules

Rules are evaluated top-to-bottom. The first matching rule wins.

Each rule has a **condition** and a **style** to apply when that condition is true.

**Condition types:**

| Condition | Applies when… |
| - | - |
| **Is empty** | Cell has no value |
| **Is not empty** | Cell has any value |
| **Equals** | Value exactly matches the given input |
| **Not equals** | Value does not match |
| **Greater than** | Numeric value exceeds the threshold |
| **Greater than or equal** | Numeric value meets or exceeds the threshold |
| **Less than** | Numeric value is below the threshold |
| **Less than or equal** | Numeric value is at or below the threshold |
| **Between** | Numeric value falls between two thresholds (inclusive) |
| **Text contains** | String value includes the given text |
| **Text does not contain** | String value does not include the given text |
| **Text starts with** | String value begins with the given text |
| **Text ends with** | String value ends with the given text |

**Style options per rule:**

| Style | Description |
| - | - |
| **Text color** | Font color (any hex, RGB, or HSL value) |
| **Background color** | Cell background color |
| **Bold** | Bold text |
| **Italic** | Italic text |
| **Underline** | Underlined text |
| **Strikethrough** | Struck-through text |

Any combination of styles can be applied in a single rule.

## Color scale

The **Scale** tab in conditional formatting applies a continuous color gradient across the column's values — useful for quickly spotting high and low values in numeric columns.

Configure three anchor points:

| Anchor | Default type | Description |
| - | - | - |
| **Min** | Minimum value in the column | Sets the color for the lowest value |
| **Mid** | *(optional)* | Midpoint color — leave blank for a two-color gradient |
| **Max** | Maximum value in the column | Sets the color for the highest value |

**Anchor types:**

| Type | Description |
| - | - |
| **Min / Max** | Automatically uses the column's actual minimum or maximum |
| **Number** | A specific absolute value |
| **Percent** | A percentage of the column's range (0–100) |
| **Percentile** | The nth percentile of values in the column |

Values between anchor points receive interpolated colors. Values outside the defined range receive the nearest anchor color.

## Table style

Open **Settings → Table Styling** to pick a preset, wrap header titles, or wrap long cell text.

| Style | Appearance |
| - | - |
| **None** | Plain table with no background colors |
| **Blue** | Blue header with light blue row banding |
| **Orange** | Orange header with warm banding |
| **Grey / Slate** | Grey header with neutral banding |
| **Yellow / Amber** | Yellow header with warm banding |
| **Green** | Green header with green banding |
| **Custom** | Choose your own header and banding colors |

### Custom style

Choose **Custom** to set header and banding colors. Review the table in both themes; the controls edit the colors for the theme currently shown.

## Pinned columns

**Pinned columns** stay fixed at the left edge of the table while the remaining columns scroll horizontally. Useful for identifier columns (e.g. name, ID) that viewers need to keep visible.

Use the column header's pin action to keep an identifier such as a customer name visible while you scroll across the table. Review the result on a narrow screen so pinned columns do not take up all the available space.

## Column order

Arrange columns in the order readers need them, with identifiers before measures. Check the table preview and save the settings when the order is ready.

## Group, pivot, and click behaviour

Use **Group** to organize rows into expandable summaries; see [Group and expand rows](/dashboards/expand-rows-in-dashboard-tables). Use **Pivot** when you want a cross-tab comparison instead of a long list.

**Click Behaviour** controls row highlighting, cell selection, and whether clicks apply dashboard filters. It also contains the **Context Menu**, **Records**, and **Drill Through** controls. **Filter Mapping** connects renamed display columns to their actual source columns.

## Expected result

The table opens with readable labels, useful number formats, and the intended default sort. Readers can find the relevant rows and use the interactions you enabled.

## Next steps

[Filter from a table value](/dashboards/filters/filter-dashboards-from-table-data) or [export table data](/dashboards/how-to/export-dashboard-reports).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.