Tab Item

On This Page

SAIL Design System guidance available for Tab Layout

When you need to organize content into easily navigable sections, use the tab layout.

About the tab item

Displays the components and layouts of a single tab within the tab layout.

Where to use the tab item

Use a!tabItem() in the tabs parameter of a!tabLayout().

Supported components

The contents parameter of a!tabItem() supports any component or layout, except:

Top-level layouts, such as a!formLayout(), a!wizardLayout(), a!paneLayout(), and a!headerContentLayout().
Subcomponents that are designed for use in a specific parameter of another component, such as a!sideBySideItem() and a!sidebarTemplate().

Parameters

a!tabItem( label, icon, contents, showWhen, validations, validationGroup, loadBehavior, id )

Name	Keyword	Types	Description
Label	label	Text	Text to display as the title for the tab.
Icon	icon	Text	Icon to display next to the label. Valid values: Any icon key. See Standard Icons for available icons.
Contents	contents	Any Type	Components and layouts to display when the tab is selected.
Show When	showWhen	Boolean	Determines if the tab is hidden and not evaluated. Default: `true`.
Validations	validations	List of Variant	Validation errors configured using a text array or an array of text and a!validationMessage(). These errors will display above the contents of the active tab and as an icon next to the tab title.
Validation Group	validationGroup	Text	The keyword used to identify the validation group for the tab item's validations parameter. When this parameter is specified, the validations parameter is only evaluated when a button that uses the same validation group is selected. This value cannot contain spaces. See the following recipes for more information: Configure Buttons with Conditional Requiredness Validation Groups for Buttons with Multiple Validation Rules
Load Behavior	loadBehavior	Text	Determines when the tab contents are evaluated. Valid values: `"ON_LOAD"` (default), `"ON_TAB_SELECT"`. `"ON_TAB_SELECT"` evaluates when the tab becomes active.
Identifier	id	Text or Integer	Unique identifier for the tab. If any tab item has an id, all tab items must have an id. If ids are not provided, the tab index is used.

Using the tab item

The following sections cover important details about the tab item.

Tab loading behavior

The loadBehavior parameter controls when tab contents are evaluated.

The two load behavior options are:

"ON_LOAD" (default): Tab contents evaluate on every evaluation cycle. Use "ON_LOAD" for tabs that load quickly or contain form inputs that use validation.
"ON_TAB_SELECT": Tab contents evaluate only when the tab becomes active. Use "ON_TAB_SELECT" for tabs with expensive queries.

Don't use "ON_TAB_SELECT" for tabs with field validations

When loadBehavior is set to "ON_TAB_SELECT", field validations in a tab item are not evaluated until the tab becomes active. If a user submits the form without selecting the tab, those validations are skipped. For this reason, use "ON_LOAD" for any tab that contains fields with validations.

For example, in the following interface, the user can submit without the required field on tab 2 being validated. Try submitting before clicking on the second tab. Then try submitting after clicking on the second tab.

a!localVariables(
  local!optionalField,
  local!requiredField,
  local!submitted: false,
  if(
    local!submitted,
    a!cardLayout(
      contents: a!richTextDisplayField(
        value: {
          a!richTextItem(
            text: "Form submitted", 
            style: "STRONG")
        },
        marginAbove: "EVEN_MORE",
        align: "CENTER"
      ),
      height: "SHORT_PLUS"
    ),
    a!formLayout(
      contents: {
        a!tabLayout(
          marginBelow: "NONE",
          contentsPadding: "EVEN_LESS",
          tabs: {
            a!tabItem(
              label: "Tab 1",
              contents: {
                a!textField(
                  label: "Optional Field",
                  value: local!optionalField,
                  saveInto: local!optionalField,
                  marginBelow: "NONE"
                )
              }
            ),
            a!tabItem(
              label: "Tab 2",
              contents: {
                a!textField(
                  label: "Required Field",
                  value: local!requiredField,
                  saveInto: local!requiredField,
                  required: true,
                  marginBelow: "NONE"
                )
              },
              /* Don't do this — required field won't be validated unless the user clicks this tab */
              loadBehavior: "ON_TAB_SELECT"
            )
          }
        )
      },
      buttons: a!buttonLayout(
        primaryButtons: a!buttonWidget(
          label: "Submit",
          saveInto: a!save(local!submitted, true),
          validate: true
        )
      )
    )
  )
)

Caching behavior for "ON_TAB_SELECT" tabs

The contents of tabs that use "ON_TAB_SELECT" are cached until a reevaluation is triggered. When the user clicks away and comes back, the original content is still there unless something else in the interface triggers a reevaluation.

Using tab identifiers

The id parameter provides a stable reference for each tab to use with the selectedTab parameter of the tab layout. Identifiers must be unique across all tab items in the same tab layout. If any tab item has an id, all tab items in that layout must have an id.

If identifiers are not provided, the tab index (starting at 1) is used as the value for selectedTab.

You must use identifiers when tabs are dynamically shown or hidden using showWhen. Because the tab indexes change when visibility changes, selectedTab could point to the wrong tab unless you are using unique identifers.

See Controlling the active tab with selectedTab for how to use identifiers with the selectedTab parameter.

Async loading placeholder

If this component relies on an async variable, a placeholder will be displayed until the async data is finished loading. See a!asyncVariable() for more information on how the placeholder behavior works.

Examples

The following examples demonstrate the tab item.

To experiment with examples, copy and paste the expression into an interface object.

Conditional tab visibility

The following example shows how to show or hide a tab based on group membership.

{
  a!tabLayout(
    tabs: {
      a!tabItem(
        label: "Dashboard",
        contents: {
          /* This is placeholder content */
          a!cardLayout(
            contents: 
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "The contents of the Dashboard tab would go here",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            ),
            showBorder: false
          )
        }
      ),
      a!tabItem(
        label: "Admin",
        icon: "lock",
        contents: {
          /* This is placeholder content */
          a!cardLayout(
            contents: 
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "The contents of the Admin tab would go here",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            ),
            showBorder: false
          )
        },
        /* If you are in the Designers group, this tab displays. Otherwise, it is hidden. */
        showWhen: a!isUserMemberOfGroup(
          username: loggedInUser(),
          /* Best practice: use a constant for the group. This example uses a!groupsByName() 
          so it works in any environment without creating a constant first. */
          groups: a!groupsByName("Designers")
        )
      )
    }
  )
}

Deferred loading for a heavy tab

The following example shows how to use loadBehavior to defer evaluation of a tab that contains an expensive query. The first four tabs use the default "ON_LOAD" behavior, while the "Historical Analytics" tab uses "ON_TAB_SELECT" so it only evaluates when a user clicks it.

{
  a!localVariables(
    local!activeTab: "overview",
    a!tabLayout(
      tabs: {
        a!tabItem(
          id: "overview",
          label: "Overview",
          icon: "home",
          contents: {
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "Overview content goes here",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            )
          }
        ),
        a!tabItem(
          id: "active",
          label: "Active Tickets",
          icon: "tasks",
          contents: {
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "Active tickets content goes here",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            )
          }
        ),
        a!tabItem(
          id: "team",
          label: "Team Workload",
          icon: "users",
          contents: {
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "Team workload content goes here",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            )
          }
        ),
        a!tabItem(
          id: "performance",
          label: "Team Performance",
          icon: "line-chart",
          contents: {
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "Team performance content goes here",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            )
          }
        ),
        a!tabItem(
          id: "analytics",
          label: "Historical Analytics",
          icon: "bar-chart",
          /* This tab contains a complex query that would slow down initial page load */
          loadBehavior: "ON_TAB_SELECT",
          contents: {
            a!richTextDisplayField(
              labelPosition: "COLLAPSED",
              value: a!richTextItem(
                text: "Historical analytics content goes here. This tab only evaluates when selected.",
                style: "EMPHASIS"
              ),
              align: "CENTER"
            )
          }
        )
      },
      selectedTab: local!activeTab,
      selectedTabSaveInto: local!activeTab
    )
  )
}

Feature compatibility

The table below lists this component's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Compatible
Offline Interfaces	Incompatible
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.
Process Autoscaling	Incompatible	Cannot be used in autoscaled processes.
Event Consumer Filter Conditions	Compatible	Can be used in filter conditions.
Event Consumer Event Handlers	Compatible	Can be used in event handler expressions.

The following recipes include usage of the Tab Item.

Trend-Over-Time Report (Charts, Reports):
This report provides an attractive, interactive design for exploring different series of data over time.

Feedback

Was this page helpful?