# object-table

## Overview

`object-table` displays data from objects retrieved from a [database query](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects) or [array](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects#arrays) in a table format.

{% hint style="info" %}
**Version compatibility**

`object-table` v3 was introduced in version 4.43.0 of the JourneyApps Container.

For older container versions, see the documentation for the deprecated [object-table v1](https://app.gitbook.com/s/aREEMGinn8s0NDYX0nNu/ui-components/object-table-v1-deprecated) and [object-table v2](https://app.gitbook.com/s/aREEMGinn8s0NDYX0nNu/ui-components/object-table-v2-deprecated).
{% endhint %}

{% hint style="success" %}
Check out the **Showcase: Object Tables** template app. It includes implementations of the most common `object-table` functionality and features.
{% endhint %}

{% hint style="success" %}
**Object tables V3**

These docs describe Object tables v3. To enable these object tables for an existing app (v3 is the default for new apps), enable the **Object tables v3** setting in OXIDE (under App Settings).
{% endhint %}

### Basic Example

{% code title="main.view\.xml" %}

```xml
<var name="users" type="query:user" />

<object-table label="Users" query="users">
    <column heading="First Name">{first_name}</column>
    <column heading="Last Name">{last_name}</column>
</object-table>
```

{% endcode %}

{% code title="main.js" %}

```javascript
function init() {
    view.users = DB.user.all();
}
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-afd47c1c48bc2b8400567a3a3d94d9c2979a66da%2Fobject-table-example.png?alt=media)

## Standard Attributes

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `query`

**Required**

**Default**: unset

`query` contains the name of the [database query](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects) or [array](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/accessing-the-database/querying-db-objects#arrays) variable to populate the objects in the `object-table`.

{% code title="main.view\.xml" %}

```xml
<var name="countries" type="query:country" />
<!-- OR -->
<var name="countries" type="array:country" />

<object-table label="Countries" query="countries">
    <column heading="Country Name">{name}</column>
    <column heading="Population">{population}</column>
</object-table>
```

{% endcode %}

## Advanced Attributes

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `automatic`

**Optional**

**Type**: `boolean`

**Default**: `true`

A `object-table` with the `automatic="false"` attribute it will automatically go into controlled mode. See the [controlled object-table](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/controlled-object-table) guide for more information.

### `bind`

{% hint style="info" %}
An `object-table` with a `bind` attribute implemented allows for a row to be 'selected'. The row is then also visually highlighted in the table.

When the bound variable changes, a digest cycle is run. It is therefore safe to rely on this variable to represent the selected state of the table at all times.

It is also possible to change the bound variable programmatically in the view code, which will cause the `object-table` to update the row. When this happens, a digest cycle is not run since the change originates from the view code.
{% endhint %}

{% content-ref url="../xml-fields/bind" %}
[bind](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/bind)
{% endcontent-ref %}

### `controls`

**Optional**

**Type**: `none` | `bottom` | `top` | `both`

**Default**: `bottom`

These include a search box and pagination controls for users to interact with the table and data. See more information in the guide on `object-table` [controls](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/controls).

### `default-filter`

{% hint style="danger" %}
**Deprecated**

`default-filter` is deprecated. Please use [`filter`](#default-filter-1) instead.
{% endhint %}

### `default-sorting`

{% hint style="danger" %}
**Deprecated**

`default-sorting` is deprecated. Please use [`sorting`](#sorting) instead.
{% endhint %}

### `empty-message`

**Optional**

**Type**: `string`

**Default**: "Your items will appear here"

Text displaying in the table when no data objects are available.

### `filter`

**Optional**

**Type**: `boolean`

**Default**: `false`

Set the default value for the [`filter`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/column#filter) attribute on all columns in the table.

### `hydrate-state`

**Optional**

**Default**: unset

This attribute is deprecated. Please use [`init-state`](#init-state) and [`on-state-change`](#on-state-change).

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `init-state`

**Optional**

**Default**: unset

`init-state` initializes an `object-table`'s state after the table is loaded using a similar structure as [`on-state-change`](#on-state-change). See more information in the guide on `object-table` [state](https://docs.journeyapps.com/reference/build/managing-component-state#object-table).

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% hint style="info" %}
**Version compatibility**

`label-color` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `limit`

**Optional**

**Type**: `integer`

**Default**: `25`

In a paginated table, the `limit` attribute determines how many rows to display on a single page. See more information in the guide on `object-table` [modes](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/mode).

### `loading`

**Optional**

**Type**: `boolean`

**Default**: `false`

A table can be put into a loading mode using the `loading="true"` property, which can also be the result of a JavaScript/TypeScript function.

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-08b417f36bf779131cb01b16cc579bc2b55b4b01%2Fobject-table-loading.png?alt=media)

{% hint style="info" %}
While a table is busy loading, it will display a placeholder loader. The table will load once it is ready.
{% endhint %}

### `mode`

**Optional**

**Type:** `paginate` | `scroll`

**Default**: `paginate`

Specifies whether a table with a number of rows should be paginates or scrollable. See more information in the guide on `object-table` [modes](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/mode).

### `min-row-height`

{% hint style="info" %}
**Version compatibility**

`min-row-height` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 38 px

Specify the minimum height of the `object-table` rows (incl. the header row). Note that `padding-vertical` may increase the actual row height.

### `on-change`

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

{% hint style="info" %}
The `on-change` attribute only has an effect if the `bind` attribute is set.
{% endhint %}

### `on-paste`

**Optional**

**Default**: unset

**Triggered when**: Data is pasted into the object-table.

**Event parameters**: See more information in the guide on `object-table` [copy & paste](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/copy-and-paste-data).

**Return value**: See more information in the guide on `object-table` [copy & paste](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/copy-and-paste-data).

`on-paste` is an event that calls a JS/TS [`$:function`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) or [navigation](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation). See more details:

{% content-ref url="../js-ts-events" %}
[js-ts-events](https://docs.journeyapps.com/reference/build/ui-components/js-ts-events)
{% endcontent-ref %}

### `on-state-change`

**Optional**

**Default**: unset

**Triggered when**: the state of the table is changed due to a UI interaction such as changing to the next page or applying a column filter.

**Event parameters**: `$state`

**Return value**: See more information in the guide on `object-table` [state](https://docs.journeyapps.com/reference/build/managing-component-state#object-table).

`on-state-change` is an event that calls a JS/TS [`$:function`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) or [navigation](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation). See more details:

{% content-ref url="../js-ts-events" %}
[js-ts-events](https://docs.journeyapps.com/reference/build/ui-components/js-ts-events)
{% endcontent-ref %}

### `on-state-changed`

This attribute is simply an alias to  [`on-state-change`](#on-state-change).

### `padding-horizontal`

{% hint style="info" %}
**Version compatibility**

`padding-horizontal` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 12 px

Specify the horizontal padding (left and right) within object-table cells (incl. header cells).

### `padding-vertical`

{% hint style="info" %}
**Version compatibility**

`padding-vertical` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 8 px

Specify the vertical padding (top and bottom) within object-table cells (incl. header cells).

### `page-count`

**Optional**

**Type**: `integer`

**Default**: unset

When an `object-table` is in controlled mode, the `page-count` attribute must reference a function which returns the total number of pages, since the table cannot determine the page count in its own. See the [controlled object-table](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/controlled-object-table) guide for more information.

### `paginate-padding-horizontal`

{% hint style="info" %}
**Version compatibility**

`paginate-padding-horizontal` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 10 px

Specify the horizontal padding (left and right) within the `object-table` pagination controls (where [`mode`](#mode) is set to `paginate`).

### `paginate-padding-vertical`

{% hint style="info" %}
**Version compatibility**

`paginate-padding-vertical` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 8 px

Specify the vertical padding (top and bottom) within the `object-table` pagination controls (where [`mode`](#mode) is set to `paginate`).

### `paginate-select-padding-horizontal`

{% hint style="info" %}
**Version compatibility**

`paginate-select-padding-horizontal` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 10 px

Specify the horizontal padding (left and right) within the page selection dropdown within the `object-table` pagination controls (where [`mode`](#mode) is set to `paginate`).

### `paginate-select-padding-vertical`

{% hint style="info" %}
**Version compatibility**

`paginate-select-padding-vertical` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 8 px

Specify the vertical padding (top and bottom) within the page selection dropdown within the `object-table` pagination controls (where [`mode`](#mode) is set to `paginate`).

### `paginate-select-text-size`

{% hint style="info" %}
**Version compatibility**

`paginate-select-text-size` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 16 px

Specify the text size within the page selection dropdown within the `object-table` pagination controls (where [`mode`](#mode) is set to `paginate`).

### `search-padding-horizontal`

{% hint style="info" %}
**Version compatibility**

`search-padding-horizontal` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 10 px

Specify the horizontal padding (left and right) within the `object-table` search box.

### `search-padding-vertical`

{% hint style="info" %}
**Version compatibility**

`search-padding-vertical` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 8 px

Specify the vertical padding (top and bottom) within the `object-table` search box.

### `search-font-size`

{% hint style="info" %}
**Version compatibility**

`search-text-size` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 16 px

Specify the text size within the `object-table` search box.

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

### `show-pagination`

{% hint style="info" %}
**Version compatibility**

`show-pagination` was introduced in version **4.89.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `boolean`

**Default**: `true`

In a paginated table, and when [`controls`](#controls) are shown, the `show-pagination` attribute can be used to show or hide the pagination controls. This may be useful for tables that only have a single page.

### `show-search`

{% hint style="info" %}
**Version compatibility**

`show-search` was introduced in version **4.89.0** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `boolean`

**Default**: `true`

When [`controls`](#controls) are shown, the `show-search` attribute can be used to show or hide the search box independent of the pagination controls.

### `sorting`

**Optional**

**Type**: `boolean`

**Default**: `true`

Set the default value for the [`sorting`](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/column#sorting) attribute on all columns in the table.

### `sticky-footer`

**Optional**

**Type**: `boolean`

**Default**: unset

When set to `true`, freezes the `object-table` `controls` (when they display at the bottom of the table).

{% hint style="info" %}
When an `object-table` has sticky headers and/or footers along with `mode="paginate"`, the controls will also be present in the corresponding sticky header or footer.
{% endhint %}

### `sticky-header`

**Optional**

**Type**: `boolean`

**Default**: unset

When set to `true`, freezes the `object-table` header.

{% hint style="info" %}
When an `object-table` has sticky headers and/or footers along with `mode="paginate"`, the controls will also be present in the corresponding sticky header or footer.
{% endhint %}

### `style`

**Optional**

**Default**: unset

References a JavaScript/TypeScript [`$:function`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml), which returns a single payload with styling information that is used to style the entire row (when set on the `object-table` level) or cell (when set on a `column` level). See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-align`

**Optional**

**Type:** `left` | `right` | `center`

**Default**: `left`

Align the text content inside a cell to the left, right or center. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-background-color`

**Optional**

**Type**: `string` - can be a named color or #HEX value

**Default**: The app's background color in light vs dark mode

The background color of the entire cell. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-bold`

**Optional**

**Type**: `boolean`

**Default**: unset

Transforms the text to **bold** if set to `true`. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-color`

**Optional**

**Type**: `string`

**Default**: Primary text color

Color of the text in a cell. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-icon-color`

**Optional**

**Type**: `string` - can be a named color or #HEX value

**Default**: Primary text color

Color of icon on the left of the cell. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-italics`

**Optional**

**Type**: `boolean`

**Default**: unset

Transforms the text to *italic* if set to `true`. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-strikethrough`

**Optional**

**Type**: `boolean`

**Default**: unset

Transforms the text to ~~strikethrough~~ if set to `true`. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `style-underline`

**Optional**

**Type**: `boolean`

**Default**: unset

Underlines text if set to `true`. See the guide on `object-table`/`column` [styles](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/object-table/object-table-guides/styles) for more information.

### `font-size`

{% hint style="info" %}
**Version compatibility**

`font-size` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**Optional**

**Type**: `integer`

**Default**: 16 px

Specify the text size within `object-table` cells (incl. header cells).

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.objectTable({id:'my-id'})` is called from JS/TS:

### `setState`

Set or update the state of the `object-table`. See more information in [this guide](https://docs.journeyapps.com/reference/build/managing-component-state#changing-the-state-from-javascript-typescript).

### `scrollIntoView`

Programmatically scroll until the `object-table` is visible in the view.

### `toggleFullscreen`

Programmatically enable or disable fullscreen mode of the `object-table`.