Free cookie consent management tool by TermsFeed a!gridField_23r3 Component
a!gridField_23r3 Component

This page contains information related to an old version of the Read-Only Grid Component.

To take advantage of the latest features and improvements, we always recommend you use the latest version whenever possible. See the latest version's page for information about what's been changed.


a!gridField_23r3( label, labelPosition, instructions, helpTooltip, emptyGridMessage, data, columns, pageSize, initialSorts, secondarySorts, pagingSaveInto, selectable, selectionStyle, selectionValue, selectionSaveInto, selectionRequired, selectionRequiredMessage, disableRowSelectionWhen, validations, validationGroup, showWhen, spacing, height, borderStyle, shadeAlternateRows, rowHeader, accessibilityText, refreshAlways, refreshAfter, refreshInterval, refreshOnReferencedVarChange, refreshOnVarChange, userFilters, showSearchBox, showRefreshButton, showExportButton, recordActions, openActionsIn, actionsDisplay, actionsStyle )

Accepts a set of data and displays it as read-only text, links, images, or rich text in a grid that supports selecting, sorting, and paging.

The a!gridField() function allows you to create a read-only grid in your interface to display data as rich text, links, images, buttons, tags, record actions, and progress bars. This grid component also supports searching, filtering, selecting, sorting, and paging.

From design mode, you can quickly and easily set up a read-only grid by dragging and dropping the component into live view and selecting your grid's data source. You can choose from record type, query, variable, rule, or expression. When you choose a record type as your data source, you can reuse features configured on your record list such as user filters, record actions, and export to Excel. You can also use fields from related records to display data on the grid.

Although, design mode allows for a easier and faster setup for your read-only grid, you can still use the a!gridField() function in expression mode to customize and configure your read-only grid.

See also:


Note:  Not all parameters are immediately available in design mode; some display only after enabling others. For example, after selecting Selectable, other selection-related parameters will be available.

Name Keyword Types Description




Text to display as the grid label.

Label Position



Determines where the label appears. Valid values:

  • ABOVE (default) Displays the label above the component.
  • ADJACENT Displays the label to the left of the component.
  • COLLAPSED Hides the label. The label will still be read by screen readers; see accessibility considerations for more information.
  • JUSTIFIED Aligns the label alongside the component starting at the edge of the page.




Supplemental text about this grid.

Help Tooltip



Displays a help icon with the specified text as a tooltip. The tooltip displays a maximum of 500 characters. The help icon does not show when the label position is "COLLAPSED".

Empty Grid Message



Text to display in the grid when no data is available. Default is "No items available".



recordType, List of Map and List of Dictionary, DataSubset, or PortalReportDataSubset

The data to display in the grid. Use a record type reference or a!recordData() to source your data from records and utilize records functionality, such as user filters and export. For other cases, you can use a query, such as a!queryEntity() with pagingInfo set as fv!pagingInfo to have the grid automatically manage paging. The function a!queryProcessAnalytics(), a Data Subset, a list of Dictionary, or an array of data can also be used. When using a query that returns a datasubset, you must pass the total count (fetchTotalCount: true on the query).



List of a!gridColumn()

The columns to display in the grid, configured using a!gridColumn().

Rows to Display Per Page


Number (Integer)

The maximum number of rows to display at a time. Default: 10

Initial Sorts


List of SortInfo

Sorts applied to the grid upon initial load only. Each sort is applied in the order listed. The first sort in the list will display an active-sort arrow indicator (either up or down for ascending or descending) in its corresponding grid column (if applicable).

Secondary Sorts


List of SortInfo

Sorts applied to the grid after every user interaction. If the user activates a sort on a column, these sorts will be applied to the other columns in the order they're listed. For example, adding a secondary sort on Month will keep them in order when the user sorts on Year. Secondary sorts do not display an active-sort indicator.

Paging Save Into


List of Save

One or more variables that are updated only when user invokes a paging action on the grid. You can reference the current paging of the grid using fv!pagingInfo.




Determines if grid rows are selectable. When selection style is "CHECKBOX" (default), the selection column is displayed. Default: false.

Selection Style



Determines the style when a row is selected. Valid values: "CHECKBOX" (default), "ROW_HIGHLIGHT".

Selection Value


Text Array or Integer Array

Identifiers of the rows that should appear as selected. Can be set to have rows be pre-selected for the user. Supported types: Text Array and Integer Array.

Save Selection To


List of Save

One or more variables that are updated with the selected identifiers when the user changes selections. Use a!save() to save a modified or alternative value to a variable. You can reference the rows selected and deselected in the most recent user interaction (not all selected or deselected rows) using fv!selectedRows and fv!deselectedRows respectively.

Selection required



Determines if a selection is required to submit the form. Default: false.

Selection Required Message



Custom message to display when a selection is required and not provided.

Disable Row Selection



Determines for each row if selection is disabled. The condition defined in this parameter is evaluated once for each row. Reference fields from the source using dot notation, such as fv!row.status, or the identifier of the row using fv!identifier. Grids that use record data must use the recordType! domain to reference a record field or related record field. For example, fv!row[recordType!Case.fields.caseName]. Default: false.



List of Variant

Validation errors to display below the grid when the data is invalid, configured using a!validationMessage(). You can reference the current page of data using fv!currentPage.

Validation Group



When present, the requiredness of the field is only evaluated when a button in the same validation group is pressed. The value for this parameter cannot contain spaces. For example, “validation group” is not a valid value. You need to add an underscore between words: “validation_group”. See the following recipes for more information:




Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.




Determines the spacing within grid cells. Valid values: "STANDARD" (web default), "DENSE" (mobile default).




Determines height of the grid. Valid values: "SHORT", "SHORT_PLUS", "MEDIUM", "MEDIUM_PLUS", "TALL", "TALL_PLUS", "EXTRA_TALL","AUTO" (default). All grid heights besides AUTO have fixed headers that will remain at the top of the grid when scrolling.

Border Style



Determines the style of the grid border. Valid values: "STANDARD" (default), "LIGHT".

Shade Alternate Rows



Determines whether alternate rows are shaded. Default: true.

Row Header


Number (Integer)

Index of the column to be used as the row header. Screen readers will announce the value in each row header when navigating to other cells within that row. Used only for accessibility; produces no visible change.

Accessibility Text



Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.

Refresh Always



When true, grid data will be refreshed after each user interaction and each interval refresh. Default: false.

Refresh After


List of Text String

Refreshes grid data each time a specified action completes. Valid values: "RECORD_ACTION".

Refresh After an Interval of Time


Number (Decimal)

How often grid data gets refreshed in minutes. When null, grid data will not be refreshed on an interval. Valid values: "0.5", "1, 2", "3", "4", "5", "10", "30", and "60".

Refresh on Reference Variable Change



When true, grid data will be refreshed each time the value of any variable referenced in the data parameter is updated. To refresh grid data when another variable that is not used in the data parameter changes, use refreshOnVarChange. Default: true.

Refresh on Variable Change


Any Type

Refreshes grid data each time any of these specific variables change. This allows you to refresh the grid data when a variable that is not referenced in the data parameter is updated. You can define a single variable (e.g. refreshOnVarChange: local!var1) or a list of variables (e.g. refreshOnVarChange: {local!var1, local!var2}).

User Filters


List of Variant

List of user filter references to display, configured using the recordType! domain. For example, recordType!Case.filters.status. You may only reference user filters defined on the source record type used for the grid data. This parameter only applies when a record type is used as the source in the data parameter.

Show search box



Determines if the record search box should be shown. This parameter only applies when a record type is used as the source in the data parameter. Default: true.

Show Refresh Button



Determines if the grid should include a refresh button to manually refresh data. This parameter only applies when a record type is used as the source in the data parameter. Default: true.

Show Export to Excel Button



Determines if grid data can be exported. This parameter only applies when a record type is used as the source in the data parameter. Default: false.

Record Actions


List of Variant

List of record action items to display above the grid, configured using a!recordActionItem(). If you use fv!identifier in the identifier parameter of a!recordActionItem(), you will also need to configure selection for the grid. This parameter only applies when a record type is used as the source in the data parameter.

Open Actions In



Determines how record actions should open to the user. Valid values: "DIALOG" (default), "NEW_TAB", "SAME_TAB".

Actions Display



Determines which details are shown for record actions, regardless of style. Valid values: "LABEL_AND_ICON" (default), "LABEL", "ICON".

Actions Display



Determines how the list of actions should be displayed above the grid. Valid values: "TOOLBAR" (default), "TOOLBAR_PRIMARY". Learn more.

Usage considerations

Using read-only grids with record data

Consider the following when using a record type as the source of your read-only grid.

Using records-powered grids in a portal

When you use records as the source for read-only grids in a portal, there are a few things to keep in mind.

In portals, you cannot use the certain record components, such as record links and record actions. When you create a read-only grid using a record type, it may automatically use these components, so be sure to remove the incompatible components before publishing your portal.

Record specific-components such as the record list search, export to Excel, and refresh buttons will all function in a portal. But keep in mind that users won't be able to save their filters. The Manage filters button is replaced with a Clear Filters button in a published portal.

Autopopulate a grid with a record list

When a record type is used as the data source for your read-only grid, Appian automatically generates grid columns based on the columns configured for the record list.

Use records-specific components

You can add user filters, export to Excel, the out-of-the-box record list search, and record actions on your grid. When you add these components, the grid will automatically style the component header for you.

See the record action component for other details to consider when adding record actions to a grid.

Display and style record actions

The recordActions parameter allows you to display record actions, like related actions or record list actions, on the grid. You can display actions from different record types.

You can then use the actionsStyle parameter to determine whether all actions display as with standard styling, or if the first record action displays as a primary button style. Appian recommends using the "TOOLBAR_PRIMARY" option when you want the first action, typically the most common action, to stand out.

When actionsStyles is set to "TOOLBAR", the buttons display like this:

When actionsStyles is set to "TOOLBAR_PRIMARY", the buttons display like this:

Record action security

Each action specified in the recordActions parameter has security that is checked to ensure only the right users can see the right actions. In most cases where you use security rules, Appian evaluates the security for the entire grid before it is shown to the user. Because security rules are verified in bulk, the overall grid loading time will be shorter than if security expressions are used.

Note:  If you use a!localVariables() inside an a!recordActionItem(), Appian cannot perform a bulk security evaluation, so the grid may load slower than expected. Whenever possible, create local variables outside a!recordActionItem().

If you use a record type with data sync enabled as the source of your grid, you can also reference related record fields in your grid.

You can use related record fields in your columns, or to sort and filter the grid.

If you reference a related record field from a one-to-many relationship as a column in the grid, the maximum number of related records returned for each base record is 10.

To filter, limit, and sort the related record set returned from the one-to-many relationship, you can leverage the relatedRecordData parameter in a!recordData().

Avoid using relationship references to display related one-to-many data. Instead, you should only reference the specific related record field you want to display. This avoids querying more data than necessary, which can impact the grid's performance and export behavior.

For example, to display a list of cases associated with each customer, you should use the related record field reference recordType!Customer.relationships.cases.fields.title in the grid column. You should not use the relationship reference recordType!Customer.relationships.cases.

Configuring grid display

  • If the value for a column is empty or null, the grid still renders the column with just the label.
  • The selectionStyle of ROW_HIGHLIGHT does not have any visual indicator when selection is disabled through the disableRowSelectionWhen parameter.
  • For accessibility purposes, every grid should have a row header configured. The first column containing text is usually the correct choice for row header. See the SAIL Design System for more information.

Configuring grid paging

  • To reduce clutter on smaller grids, the following happens:
    • No paging controls are displayed when all rows are on one page.
    • Paging controls to jump to the first or last page are not displayed when a grid has less than 3 pages.
  • When a read-only grid is used offline, paging and sorting don't function and images won't render.
  • If you are managing your own paging, you cannot pass a datasubset which has a paging configuration that uses a batch size of -1.
  • When entering a query in the data parameter (either directly, or indirectly from a rule reference), the query must return the total count (fetchTotalCount: true).

Grid height and column width

  • Grid heights behave as a fixed height on web but a maximum height on mobile.

  • For columns using the "AUTO" width, each column's width is determined by the length of the longest value in that column.

Design mode guidance

Note:  This guidance does not apply to grids that use a record type as the data source. See Configuring the Read-Only Grid to learn how to configure a records-powered grid in design mode.

The following guidance applies when configuring a read-only grid in design mode:

  • Generated columns:
    • When you populate the data parameter from design mode and let the grid manage the paging, the grid will automatically generate an initial set of columns in the order they appear.
    • Grid columns are not automatically generated when you select VARIABLE as the data source and use a local variable to power the read-only grid.
    • The initial values for automatically-generated columns are:
    Parameter Value Description
    label fv!row.<fieldname> The field name is converted to title case. If the field name is in camel case, it will be split and converted to title case. If the field name is too long, it will be truncated with ellipses (...).
    value fv!row.<fieldname> The field value to display.
    sortField <fieldname> The field name of the primary key.
    align "END" or fixed() The alignment depends on the field's data type. If the data type for the column value is numerical or date-based, then it will set align : "END". If the data type for the column value is a decimal, then it will be wrapped in the fixed() function to two decimal places. Ex. value: fixed(fv!row.cost, 2).
  • Updating columns:
    • After initial columns have been generated, the grid will automatically update with new columns to match any new fields added to the data source.
    • However, automatic updates do not occur when the data source is an RULE or EXPRESSION. To update the columns displayed in the grid, you must update the data source, and add or remove the columns manually.
  • Selecting QUERY as the data source:
    • If you select QUERY as the data source, you'll use the query editor to configure the query that powers your grid.
    • Appian will automatically use the following query values in your grid:
      • The query's batchSize will be the value of the grid's pageSize parameter.
      • The query's sortInfo will be used as the grid's initialSort parameter.
  • Batch size limitation:
    • The grid cannot use a query that has a paging info with a batch size of -1 in design mode.


You can find example configurations of the grid at Configuring the Read-Only Grid and Grid Tutorial.

Feature compatibility

The table below lists this SAIL component's compatibility with various features in Appian.
Feature Compatibility Note
Portals Compatible
Offline Mobile Compatible
Sync-Time Custom Record Fields Incompatible
Real-Time Custom Record Fields Incompatible

Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.

Process Reports Incompatible

Cannot be used to configure a process report.

Process Events Incompatible

Cannot be used to configure a process event node, such as a start event or timer event.

Open in Github Built: Thu, May 23, 2024 (08:48:06 PM)

a!gridField_23r3 Component