List

A data component, the List displays a roster of record items, which can be formatted in a template using merge syntax to control how the items render. This component allows end users to employ on-click actions from the List items to launch actions in other components on the page.

Jump to:

Using the List component

While typically employed with the Action Framework to update Page Includes on the page, the List can be used for a variety of purposes.

One common use case for this component is to put a List in a Responsive Grid section that lists records by name. When a name is selected, data from a different Nintex Apps page is displayed via a Page Include (in another section of the grid).

Note:  The content below assumes you have a Nintex Apps page and at least one working model.

Add a List component to the page, then:

  • Ensure that the List is accessing the correct model and name the List ( if desired ). ( General tab)
  • Determine what items display on the list by clicking Add fields on the component.
  • Choose whether to include a search box. ( Search tab)
  • Give end users the ability to sort records based on field values. ( Sort tab)
  • Add Interactions that allow users to launch action when they select a List item. For more information, see Interactions tab in Component properties.

Every List includes a header and pagination. Depending on the property settings, these sections can include various features. For more information, see the Headers and Pagination tabs in Component properties.

Add items to a List

The power of the List component is in the items you choose to place on that List. Nintex Apps gives you a lot of options from the Add feature and Add fields dropdown menus on the List component.

Customize the List display with any of the items from the Add features dropdown menu.

  • Row Actions: Record-level actions represented by row buttons that use a record on the component as the context.
  • Mass Actions: Enables the ability to select one or more records. Each selected row becomes context for the mass action.
  • List filter: Add filters to the header of the List component.

Customize the List display with any of the items from the Add fields dropdown menu.

  • Model fields: Displays a field's name on the list.
  • Template: Allows builders to add multiple field names (along with punctuation or symbols such as "+") and display on the List.
  • Avatar: Displays a small "avatar" image on the List.
  • Icon: Displays an icon on the list.
  • Image: Displays an image on the list.

When multiple items are added to the List, they are displayed in the order they appear in the Page Designer. To change the order, drag and drop the item by clicking on the Item's column header.

In addition to adding multiple items to the List, you can also add fields to any item creating a "column" within the List:

  • From the item's column header, click Add fields.

Add Button Group

From the Add fields dropdown in a column, add a button group directly into the List component.

When you add buttons to the List component, these buttons have their own properties. All List button properties are the same as those for Ink Button Set buttons.

Configure List items

Configure the item's properties (including formatting a Template or selecting the image source for Avatars, Icons, and Images) by clicking the Item's name to open the Field properties pane.

Configure the layout of individual item columns in the List by clicking the item's column header to open the Column properties pane.

Component actions

Component actions are available using Run component action.

Navigates to the Target page in the component.

  • Target page:
    • First page
    • Last page
    • Previous page
    • Next page

Opens drawers for all rows in the selected List.

Closes drawers for all rows in the selected List.

Component properties

  • Unique Id: An automatically generated alphanumeric identifier for the component. You can rename if needed. (Required)

  • Model: Specifies the data source that the component will display.

  • Style variant: Style variants are created and set in the Design System Studio. Some components have pre-defined variants for a specific aspect of a component's style. Nintex Apps builders can style and customize elements to create their own themes within the DSS. These themes will dynamically populate as selectable values in the Style variant drop-down menu.

    Note: 

    • To refresh available style variant options, click Refresh style variants.

    • This is useful for when changes to the design system (like style variants or variable options) have been made in another browser window or by another user.

  • Margins: Sets a component's margin (the space around it) relative to other components on the page.

    • To set margins for all sides, click All.

    • To set margins for each side individually, click Separate.

    Margins must be set using spacing variables defined in the design system. Custom or arbitrary values are not allowed. For more information, see Spacing.

  • Show header: To display the header on the component, turn on the toggle.

  • Allow HTML in title: Determines HTML rendering behavior for Title contents.

    • When turned on, any HTML syntax will be rendered. For example, This text is important.

    • When turned off, HTML syntax is displayed as plain text. For example, <strong>This text is important</strong>.

  • Title: Title that is displayed on the component. If left blank, the component will not display a title. It can also contain rendered HTML if Allow HTML in title toggle is turned on.

  • Show pagination: To display the pagination on the component, turn on the toggle.

  • Records per page: Manages how many rows are visible on the component. Select an option from the drop-down menu or enter a custom number.

  • Show records per page dropdown: To display a drop-down menu on the component that allows users to select how many records to view per page, turn on the toggle.

  • Show "Load more" button: To display the Load More button on the component, turn on the toggle. The model’s Max # of records determines the initial number of records shown. Users can click the Load More button to load additional records.

  • Reset pagination on query: To reset pagination to the first page after any edits or queries to the model, turn on the toggle.

  • Row actions on left: By default, row actions appear on the right. To display them on the left, turn on the toggle.

  • Enable drawers: To add a left arrow ( >) next to fields, icons, avatars, or images in the list, turn on the toggle. Once turned on, click the left arrow ( >) or select Configure Drawer to open the Drawer modal.
  • Show search box: To display the search box on the component, turn on the toggle.

  • Search method: Determines if a search will query the server and filter its data, or filter local data on the client. Select one of the following options.

    • Server (Default): Returns search results from all data on the server.

    • Client: Returns search results only from the data currently loaded on the page. For large datasets, this can reduce filtering time. If users typically filter only the visible data rather than all records on the server, enabling this option may improve performance.

      Note:  If the server contains a large data set that hasn't been fully loaded on the page, and the Search method is set to Client, the filter may return incomplete results, as it can only filter the data currently available. This may lead to unexpected omissions.

  • Search results: Determines which results are displayed based on the search query. Select one of the following options.

    • Match exactly: Results are only shown for records that match the search term.

      For example, if the search text is George Washington, only records that contain George Washington exactly as written, with no additional words in between will be displayed.

    • Contain all terms: Results are shown for records that contain all of the terms in the query, even if they may appear in a different order or disconnected from each other.

      For example, if the search text is George Washington, any record that contains both George and Washington, regardless of their order or placement will be displayed.

    • Contain at least one term: Results are shown for records that contain any of the terms in the query.

      For example, if the search text is George Washington, any record containing either George or Washington will be displayed.

  • Search box placeholder text: Type the custom text to display as placeholder text in the search box until the user starts typing.

  • Search icon display: Determines how the search icon is displayed. Select one of the following options.

    • Button: Appears as an icon inside the search box that users can click to perform a search.

    • Inset icon: Appears inside the search box and not meant to be clicked.

    • None

  • Search icon: Determines the search icon that is displayed inside the search box. To edit and reset the selected icon, click .

  • Empty search behavior: When the search box is cleared, the model is re-queried without any search conditions, so records are likely to be returned. To remove all records from the model when the search box is emptied, select Remove all model data. Select one of the following options.

    • Re-query for model data: Clears the search term and retrieves all records from the model.

    • Remove all model data: Clears the search term and removes all records from the model.

  • ARIA label: Determines what description will be read by assistive technology, such as screen readers, by setting the aria-label HTML attribute, which is part of the Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA) spec.

    Used to describe elements where text may not be visible, this property can be a specific string of text, the merge variables of one or more fields, or a combination of the two.

  • Search fields: Specifies which fields will be searched against from the component's search bar.

    Note: 

    Depending on the connection used for the model attached to the component, this property may not be available.

    • Field: Nintex Apps searches on searchable fields by default. Search can be narrowed to individual fields by clicking add Add new Search Field, and then using the field picker to select the field.

      Note: 
      • ( Salesforce connections only ) SOQL can search Picklist fields and Reference fields, but not Long Text fields.
      • You can add multiple search fields.

      • Search operator: Select from the following logical operators:

        • =
        • starts with
        • Contains

By default, Salesforce Objects use SOQL. To ensure proper functionality, enable the Allow Search property on any Salesforce objects to be included in the search. For more information see, Make Search Faster.

For more information on using these search options with Salesforce, see Salesforce's SOQL and SOSL Reference Guide.

  • Show Sort Builder: To display the sort builder on the component, turn on the toggle.
    • Button icon: Determines the sort icon that is displayed on the sort builder. To edit and reset the selected icon, click .
    • Button label: The label text that appears on the sort builder. Type the text you want to display to users.

  • Sort client-side: To sort only the field values already loaded on the page, turn on the toggle. This applies sorting only to the data currently in the model, not to any data still on the server.

Interactions trigger Action Flows based on typical ways an end user may interact with a page element or component. Interactions can be configured on various elements. Options vary, but may include:

  • Click

  • Right click

Note: 

You can use Page Include with your list. For more information, see Run component action.

  • Nintex Apps page: The name of the associated page.
  • Page Include component Id: Click to select the Page Include from the list. ( If you have given the Page Include a unique name, it will appear here ). When a Page Include is selected, a flashing yellow outline will indicate the chosen item within the canvas.
  • Query string: Use id={{Id}}. This tells the Page Include to load the record whose ID matches the ID of the record the end user clicked.

Standard display logic options are available to display or hide the component or feature.

Nested elements

When you add items to a List, there are several properties you can modify:

Click the item (Field, Template, Avatar, Icon, or Image) element to configure the following options:

  • Width behavior: Determines the way items fill the List.
    • Fill: Allots a percentage of the space to the selected item, based on the fill ratio.
      • Fill Ratio: This sets the amount of space for this item relative to other items in the List. For example, a flex ratio of 2 will be double the width of an item with a flex ratio of 1.
    • Fixed: Allots a fixed amount of the space to the selected item, based on the Width settings.
      • Width
        • Extra Small
        • Small ( default )
        • Medium
        • Large
        • Extra Large
        • Custom
          • Custom width amount: This can be specified using px, em, %, vh, or vw measurements.

Click the item (Field, Template) element to configure the following options:

  • Type:

    • Field: Uses the field Id, i.e. {{Name}}
    • Field label: Uses the plain language field name, ie., Account Name.
    • Template: Opens the Template property field.
      • Template: The fields (selected using the field picker) to display in the queue.

  • Display style override: By default, any additional fields added to an item use the default text styling. To override that, select one of the following additional style options (all of which are configured in the Design System Studio)

    • None
    • Style 1
    • Style 2
    • Style 3

  • Field: The field to use for the list item. Select from the picklist.

Click the item (Avatar, Icon, or Image) element to configure the following options:

  • Style variant: The format of the Avatar

  • Image URL: The URL for the image to be used as the Avatar. Or, pick an Image field from the picklist.

  • Icon: The image to be used as the icon. Select from the picklist.

  • Alternate text: Add descriptive text about the image that can be used by access/assistive technologies such as screen readers and conforms to Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA ) specifications. This property can be a specific string of text, the merge variables of one or more fields, or a combination of the two. Alt text also increases a search engine's ability to index the image.

    Note:  If no Alternative Text is specified, access/assistive technologies will either ignore the image, or (in some cases) speak a generic label, such as "Image displayed."

  • Size: The size of the Avatar or Icon.

    • X-Small
    • Small
    • Medium
    • Large

  • Fallback type: An alternative if there is not an Avatar available.

    • Text: Replacement text for the Avatar.
      • Fallback text: The text to be displayed instead of the Avatar.
    • Icon: Replacement text for the Avatar.
      • Fallback icon: The icon to be displayed instead of the Avatar.

Show drawer icon: Determines whether or not to display an icon next to the record. If unchecked, the drawer can be opened and closed by configuring a global action (in a Table component) or row action (in a Table or List component) to run the Open/Close A Drawer action.

Icon: Click the icon picker to select a different icon.

Configure drawer: Opens the drawer configuration modal.

Before Load Actions refers to actions used before a drawer is loaded. Generally, these actions are used to activate and set the values of model conditions, and to query models to ensure that the contextually-relevant data will display in the drawer.

For more information, see Add Nested Rows to your Table with Drawers.

Context variables for context containers are managed from the Context variables property section. For more information about context variables, see the Context topic.