Managing Component State

Many JourneyApps UI components maintain internal state that controls pagination, search, selection, sorting (where applicable), and more. The two components that offer the most comprehensive state management features are:

• object-table — tabular data display with sorting, filtering, editing, selection, etc.

• list — card-style or simple item listing with pagination, search, and single selection.

Managing state is considered an advanced topic. In most cases, both components work very well using default behavior without any manual state control.

Shared Concepts

Both object-table and list support the same three main mechanisms for reading and controlling state:

1. on-state-change Called whenever the user interacts with the component in a way that changes its state (paging, searching, selecting, etc.).

2. init-state Sets the initial state when the view is loaded (very useful for preserving user preferences when returning to a view).

3. Programmatic setState() via JavaScript/TypeScript component.objectTable({ id: "…" }).setState(…) or component.list({ id: "…" }).setState(…) Allows updating state after the view has loaded (e.g. reset filters on button press, jump to page X, clear search).

When to prefer one method over the other

• Use init-state for most cases — it runs once on view load and is perfect for remembering pagination/search/selection when users navigate back.

• Use setState() only when you need to change state dynamically after the view has loaded (e.g. button resets table, syncs two components, etc.).

Supported components Currently only the following components expose this state management API:

• object-table

• list

---

Data displayed in an list and object-table is controlled by its state. The objects provided below list all of the properties which can be safely accessed and mutated from JavaScript/TypeScript.

Advanced topic

Managing state is considered an advanced topic. In most cases a component can be used effectively without directly managing its state.

on-state-change

The function specified in on-state-change is called when the state of the table or the list is changed due to a UX/UI interaction such as changing to the next page. The $state parameter can be passed to the function which contains a simplified JavaScript/TypeScript object of the component's state.

object-table

<object-table on-state-change="$:tableStateChange($state)">
    ...
</object-table>

main.ts

function tableStateChange(tableState){
    // tableState contains the table's current state
    console.log(JSON.stringify(tableState));
}

list

The internal structure of $state is as follows:

object-tabe

The validationErrors field is available from Runtime 4.90.9+. It is handled internally and therefore cannot be set by the developer via the setState or init-state logic.

main.ts

interface State{
  filters: {
    /**
     * Contains the payloads for the filters that are applied. Note that each type of filter is unique, and is identified
     * using the `factory` variable
     */
    [key: string]: {
      factory: string;
      
      /**
       * current evaluated title of the column
       */
      column: string;
    }
  };
  /**
   * the global search applied on the table
   */
  search: string | null;
  /**
   * current limit applied to the table (might be user-adjustable in the future which is why it is available here) 
   */
  limit: number;
  /**
   * Current page of the table, starts at 1
   */
  page: number;
  /**
   * All the columns being sorted, and in the sort order.
   */
  sorting: Array<{
    /**
     * current evaluated title of the column
     */
    column: string;
    key: string;
    type: 'asc' | 'desc' | 'none';
  }>;
  /**
   * Which cell is currently in edit mode, or null otherwise
   */
  editing: {
    id: string;
    column: string;
  } | null;
  /**
   * An array of cells which are currently selected (which can include clusters of selected cells)
   */
  selected: Array<{
    id: string;
    column: string;
  }>;
  /**
   * Indicates if the table is in full screen mode or not
   */
  fullscreen: boolean;
  /**
   * Callouts which are currently visible in the table.
   */
  callouts: Array<{
    message: string;
    color: string;
    id: string;
    column: string;
  }>
  /**
   * Validation errors currently present on the table
   * (Available from Runtime 4.90.9+)
   */  
  validationErrors: Array<{
    message: string;
    id: string;
    column: string;
  }>
}

column properties: The state payload will in contain column properties which refer to the current name of the column. This is provided as convenience data to make working with the state easier, but it is not used when initializing state since the value can change dynamically. Using the column data to initialize the state is therefore considered unsafe and should not be relied on.

list

init-state

A table or list can initialize its internal state after the component is loaded using a similar structure as on-state-change.

How init-state differs from on-state-change:

• For the object-table components, init-state will ignore column fields (it only uses column key information)

object-table

<object-table init-state="$:initState()">
  ...
</object-table>

main.ts

function initState(){
    /**
     * @type ReturnState
     */ 
    return { page: 1, fullScreeb: true, ... }
}

list

The internal structure of the returned state object is as follows:

object-table

main.ts

interface ReturnState{
  filters: {
    /**
     * Will contain the payloads for the filters that are applied. Note that each type of filter is unique, and is identified
     * using the `factory` variable
     */
    [key: string]: {
      factory: string;
    }
  };
  /**
   * the global search applied on the table
   */
  search: string | null;
  /**
   * current limit applied to the table (might be user-adjustable in the future which is why it is available here) 
   */
  limit: number;
  /**
   * Current page of the table, starts at 1
   */
  page: number;
  /**
   * All the columns being sorted, and in the sort order.
   */
  sorting: {
    key: string;
    type: 'asc' | 'desc' | 'none';
  }[];
  
  /**
   * Indicates whether the table is in a full screen state or not  
   */
  fullscreen: boolean;
}

Note: The validationErrors field is handled internally and cannot be set by the developer.

list

Changing the state from JavaScript/TypeScript

To change the state of the table or list using JavaScript/TypeScript, make use of the component.objectTable({ id: "my-id" }).setState({ ... }) method or component.list({ id: "my-id" }).setState({ ... }). This method requires an id="" attribute to be present on the object-table that matches the id used in above component.objectTable().

Note: The setState() method takes the exact same payload as init-state="".

For example:

object-table

main.ts

function updateState(){
    component.objectTable({ id: "my-table" }).setState({ page: 1, search: ''});
}

<object-table id="my-table">
    ...
</object-table>

list

When to use setState() vs init-state=""

Since both of these methods do the same thing but in different parts of an application, it is important to understand why and when you should use one over the other. In most JourneyApps applications, init-state="" is the easiest to use because it is called only once when the view loads. This is particularly useful when users navigate using a table, and when they return to the table they expect it to look exactly the same as before.

setState() is useful when a developer needs to control or manipulate the table after the view has loaded. Actions such as changing the page and updating the select cell are events that should not fire on every update on a view, but rather when very specific events occur, such as pressing a particular button.

Tip: Implementing setState() can slow down your view if done frequently. Use it only where init-state="" is not feasible.

---