> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/library/ui-components/table.md).

# Table

A **Table** is an iterating component that displays structured data from a data source containing multiple objects (cardinality *Many*). Each row represents one object, which acts as the *object in context* for that row. This lets you add adornments whose events run in the context of the row object, for example to open the details of a single record.

The table is read-only by default and supports sorting, filtering, search, row selection, inline editing, and data export, all configured through the settings described below.

{% hint style="info" %}
Showroom: [table example](https://showroom.appfarm.app/ui-components/table), with its setup in Appfarm Create ([register](https://showroom.appfarm.app/sign-up) for access).
{% endhint %}

## Usage

Tables are suited to data overview, search, filtering, and structured display. They work well in administrative applications, where users browse data with various filters and the data has many columns. When the priority is a highly customized interface, for example a consumer-facing app, a custom layout may be a better fit than a table.

## Data

Set the data to display in the setting **Data source**. This can be a data source or a [multi-reference property](https://docs.appfarm.io/reference/data-model/object-class-properties.md#general-properties). By default the table shows all objects in the data source.

When **Data source** is a multi-reference property, **Filter**, **Conditional filters**, **Sorting**, **Skip**, **Limit**, **Row selection** and **Edit mode** are not available.

To show a subset, apply a **Filter** on the table. You can also add **Conditional filters**, which are enabled or disabled at runtime. Each conditional filter has a *condition* that determines whether it applies and a *filter* that is added on top of the top-level filter. All conditional filters evaluated as enabled apply together.

{% tabs %}
{% tab title="Example" %}
A solution displays projects in a table, with a radio button above the table for selecting the project state. When the user selects a state, a conditional filter is enabled that filters the projects to the selected state.
{% endtab %}
{% endtabs %}

Use **Sorting** to set the initial sort order. Users can re-sort by clicking a column header. To control how many objects are shown, use **Skip** to skip the first *n* objects and **Limit** to set the maximum number displayed.

If the data source is large, the table can take time to render. Enable **Pagination** to render a set number of rows per page and page through the data. This is especially useful when the table uses many adornments or property conditions.

## Columns

Each column shows a **Value** in its cell, typically a property from the data source, though a static value or a function can also be used (for example, `return firstname + " " + lastname`). Setting a value is not required, for example when a column contains only a button added as an adornment.

The following settings are available per column:

| Property                  | Description                                                                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Value**                 | The property, static value, or function shown in the cell.                                                                                                                |
| **Column data type**      | The data type of the value. Available when **Value** is a function.                                                                                                       |
| **Column title**          | The header shown for the column.                                                                                                                                          |
| **Title tooltip**         | A tooltip shown for the column header.                                                                                                                                    |
| **Column visible**        | Shows or hides the column based on a condition, for example to hide a column from certain user groups.                                                                    |
| **Multiline**             | Renders line breaks in read mode and supports entering them in edit mode.                                                                                                 |
| **Show as text**          | For boolean values, shows the boolean labels instead of checkmarks.                                                                                                       |
| **Number format**         | For number values, sets how the number is formatted. Set **Currency** when the format is currency, and use **Decimal places** and **Group digits** to control the output. |
| **Hide value**            | Hides the value in the cell while still letting users sort by the column.                                                                                                 |
| **Sortable**              | Allows users to sort by the column from its header. Enabled by default.                                                                                                   |
| **Initially hidden**      | Hides the column until the user adds it. Available when **Show/Hide Columns** is enabled on the toolbar.                                                                  |
| **No search / No filter** | Excludes the column from search or filtering. Available when **Search** or **Filter** is enabled on the toolbar.                                                          |
| **Autocomplete**          | Shows an autocomplete field for the column in the table filter. Available for string values read through a reference.                                                     |

For columns that reference other objects (enumerated types or object classes), you can set which options are available. When edit mode is enabled, you can also set a column to be read-only or disabled.

### Adornments

Add **Adornments** to a column to show icons, icon buttons, buttons or avatars in its cells. Each adornment has these settings:

| Property                              | Description                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Variant**                           | Avatar, Button, Icon or Icon Button (default).                                                         |
| **Title**                             | The tooltip, the label of a Button, or the menu item text of an Icon Button in the menu.               |
| **Avatar image**                      | The image of an Avatar.                                                                                |
| **Position**                          | Places the adornment at the start (default) or end of the cell. Not shown when **In menu** is checked. |
| **Icon** / **Icon value**             | A static icon, or an icon from an enum value.                                                          |
| **Icon placement**                    | Where the icon sits on a Button.                                                                       |
| **Button color** / **Button variant** | For a Button. Defaults are Primary and Outlined.                                                       |
| **Color**                             | The color of an Icon, Icon Button or Avatar.                                                           |
| **In menu**                           | For an Icon Button. Places the adornment in a menu in the cell.                                        |
| **Show on hover**                     | Shows the adornment only while the row is hovered.                                                     |
| **Visible** / **Disabled**            | Shows, hides or disables the adornment, for example based on a condition.                              |
| **On click**                          | For a Button or Icon Button. Runs an action with the row object in context.                            |

### Column style

Each column has a **Column style** section with **Header rotation**, **Align content** (default `Left`), **Border right**, **Disable padding**, **Column width**, **Sticky column**, **Text color** and **Background color**.

**Sticky column** keeps the column to the left when the table scrolls horizontally. To keep several columns sticky, give every sticky column except the last a fixed **Column width**, and set **Sticky offset** on each column to the total width of the sticky columns before it.

### Conditional properties

**Column conditions** set a column to **Initially hidden** based on a condition, without requiring **Show/Hide Columns** to be enabled on the table.

**Conditional Cell Properties** change the text and background color of a cell based on a condition. Conditions are evaluated in the context of the current row, so you can style a cell using any property stored on the row object.

### Add all properties as columns

The **Add all columns** button adds every object class property and runtime property of the data source as columns. A reference property is added only if its referenced object class has a [Display Property](https://docs.appfarm.io/reference/data-model/object-classes.md#general-properties) set. For example, adding all columns for a `Contacts` data source with a `Contact.Company` reference adds `Contact.Company.Name` as a column when the `Company` object class has `Name` as its display property.

## Row selection

Turn on **Row selection** to let users select rows. The setting is data-bound, so selection can be toggled at runtime. Selecting rows flags the corresponding objects in the data source as *selected*, and deselecting clears the flag.

Selection is *multiple* by default and adds a checkbox at the start of each row. Enable **Single select** to allow only one selection at a time. To show how many rows are selected, enable **Selection count** on the toolbar.

## Edit mode

The table is read-only by default. Enable **Edit mode**, a data-bound setting, to render the cells as input fields. Per column, you can set whether the column is *read-only* or *disabled* in edit mode. Reference properties are shown as selects, with their own settings for which options are available. You can also run an action **On value change**.

When **Edit mode** is on and a column's **Value** is bound to a property, the column gets an **Edit mode** section. Which settings show depends on the data type:

| Property                                 | Shown for                          | Description                                                             |
| ---------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| **Update on keypress**                   | String, Integer, Float             | Writes the value on every keypress.                                     |
| **No stepping**                          | Integer, Float, Duration           | Turns off changing the value with the arrow keys and mouse wheel.       |
| **Edit variant**                         | Boolean                            | Checkbox (default) or another input type for the value.                 |
| **Options**                              | Reference                          | The data source that holds the objects to choose from.                  |
| **Display value** / **Filter**           | Reference, when **Options** is set | The property shown for each option, and a filter on the options.        |
| **Allow null**                           | Enum, or Boolean shown as a select | Adds an empty option so the user can clear the value.                   |
| **Limit options** / **Selectable enums** | Enum                               | Limits the dropdown to the enum values you select.                      |
| **Datepicker type**                      | Datetime                           | Date (default), Time or Date and Time.                                  |
| **Min date** / **Max date**              | Datetime, unless the type is Time  | The earliest and latest date the user can pick.                         |
| **Read-only** / **Disabled**             | All                                | Keeps the column read-only or disabled while the table is in edit mode. |
| **On value change**                      | All                                | Runs an action when the user changes the value.                         |

{% tabs %}
{% tab title="Example" %}
An inventory table lists products with their details and a column for stock. The product details are read-only, while the stock column can be edited to adjust inventory levels.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
When displaying a lot of data, consider using an adornment button that opens a dialog to change the row object, rather than making the whole table editable. This can perform better and is often clearer for the user.
{% endhint %}

## Appearance

**Hover row** highlights the row under the mouse pointer and is enabled by default. **Compact table** reduces the row height.

## Toolbar

Enable the **Toolbar** to show a toolbar above the table. You can set a data-bound title in **Toolbar title**, which supports the `{{totalRowCount}}` parameter to display the total number of rows. If row selection is enabled, you can also show the **Selection count**.

The toolbar has several built-in actions you can enable:

| Action                | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| **Search**            | An inline search field that searches across all columns.                                       |
| **Filter**            | A popover with filters for each column.                                                        |
| **Show/Hide Columns** | Lets users add or remove columns. Columns can be set **Initially hidden** at the column level. |
| **Data export**       | Lets users export the table content to a file.                                                 |

To exclude a column from search or filtering, enable **No search** or **No filter** at the column level.

### Data export

Turn on **Data export** to let users export the table content to a file, then set **Format** to either **CSV** (default) or **Excel (.xlsx)**. Enable **No headers** if the exported file should omit the header row. For CSV, set the **Delimiter** to `;` for European users, where CSV files use a semicolon as the column separator, as opposed to US users, where `,` is used. The default delimiter is `,`. Enable **Strings in quotes** to wrap text values in quotes. **Delimiter** and **Strings in quotes** are not available for Excel.

### Custom toolbar actions

Besides the built-in actions, you can add your own toolbar actions, either as single actions or grouped in a dropdown menu. An action can be limited so that it is available only when one or more rows are selected.

Add them under **Toolbar Actions**. Each action has a **Title**, an **Icon** (default a star), **On selection** (the action is hidden on the toolbar, or disabled in a dropdown menu, until a row is selected), **Dropdown menu** (shows the action in a menu opened by a menu button), **Visible**, **Disabled** and an **On click** action.

## Footer

Turn on **Footer** to show aggregated values for the columns. Once enabled, use the per-column setting **Footer type** to choose which columns have a footer and which aggregate function each one uses.

The footer settings show on columns with Integer, Float or Duration values:

* **Footer type**: None (default), Sum, Count, Average or Custom Value.
* **Footer label**: A left-aligned text in the footer cell, for example `Sum`.
* **Footer value**: For Integer and Float columns, a value of your own to show in the footer.

## Header

The header can be fixed with **Fixed header**, so it sticks to the top of the page when scrolling, or hidden entirely with **Hide header**.

{% hint style="warning" %}
For a fixed header to work, you may need to set the height of the table to 100%.
{% endhint %}

## Pagination

Turn on **Pagination** to split the rows into pages. **Rows per page** sets the number of rows on each page, and defaults to 10. When row selection with multiple select is enabled, **Select all pages** shows a banner that offers to select all rows across all pages once the current page is fully selected.

## Events

**On row click** runs an action when the user clicks a row. It does not run while **Edit mode** is active.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appfarm.io/library/ui-components/table.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
