{"title":"Designing list pages","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-designing-list-pages/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-designing-list-pages, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-designing-list-pages","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to design Business Central list pages with clear layouts, useful actions, filters, tile views, and device-specific behavior.","date":"2026-11-05","meta":{"topic":"concept-article"},"outline":[{"level":2,"title":"Overview<#tab/about>","slug":"overviewtababout","at":113,"chars":1421},{"level":3,"title":"Customizing list pages from the client","slug":"customizing-list-pages-from-the-client","at":1112,"chars":422},{"level":2,"title":"#tab/structure","slug":"tabstructure","at":1534,"chars":4431},{"level":3,"title":"General definition","slug":"general-definition","at":1552,"chars":454},{"level":3,"title":"Structure","slug":"structure","at":2006,"chars":3959},{"level":2,"title":"Behavior points<#tab/behavior>","slug":"behavior-pointstabbehavior","at":5965,"chars":1349},{"level":2,"title":"Developer tips<#tab/tips>","slug":"developer-tipstabtips","at":7314,"chars":1056},{"level":2,"title":"Designing for devices<#tab/targets>","slug":"designing-for-devicestabtargets","at":8370,"chars":1425},{"level":3,"title":"Prioritize the visible columns","slug":"prioritize-the-visible-columns","at":8622,"chars":254},{"level":3,"title":"Design for tile views","slug":"design-for-tile-views","at":8876,"chars":340},{"level":3,"title":"Promote frequently used actions","slug":"promote-frequently-used-actions","at":9216,"chars":168},{"level":3,"title":"Configure actions to display in shortcut menu on rows","slug":"configure-actions-to-display-in-shortcut-menu-on-rows","at":9384,"chars":241},{"level":3,"title":"Configure the gesture for actions","slug":"configure-the-gesture-for-actions","at":9625,"chars":170},{"level":2,"title":"Related information","slug":"related-information","at":9795,"chars":340}],"text":"The List page type displays records from an underlying table, either as rows and columns or as individual tiles.\n## Overview<#tab/about>\nYou design list pages when you want to provide users with a collection of data, enabling them to get an overview of and find entities to work with, such as customers, vendors, or sales orders. Typically, a list page will link to an associated card page that lets users view or modify specific entities in the list.\nThere are different ways to make a list page available in the application:\n Make the list page available from the navigation of a role center page.\n  This option gives users quick access to the page. The list opens in the content area of the role center, with the navigation area still available at the top. See devenv-designing-role-centers.\n Make the list page available from an action on another page.\n  The list page opens over the current page rather than embedded in the role center.\n Make the list page searchable from Tell Me.\n  The list page also opens over the current page. See Adding pages and reports to search<devenv-al-menusuite-functionality>.\n### Customizing list pages from the client\nUsers can personalize list pages by rearranging or hiding columns, actions, and FactBoxes. See Personalizing your workspace</ui-personalization-user>.\nAs a developer or administrator, you can use Designer in a Business Central online sandbox to customize list pages. Package the changes in an extension to deploy them for other users. See Use Designer<devenv-inclient-designer>.\n## #tab/structure\n### General definition\nA list page is defined by a page that has the properties/devenv-pagetype-property set to List and properties/devenv-sourcetable-property set to the table object that contains the records that you want to display.\nTo associate a list page with a card page, which enables users to view, edit, or create records, set the properties/devenv-cardpageid-property on the list page.\nFor a code example, see devenv-simple-list-page-example.\n### Structure\nThe following illustration identifies the main areas of a list page. Action placement can differ by version and configuration.\n![Annotated Business Central list page showing list and tile views, actions, FactBoxes, search, and the filter pane.]\nThe following table describes the elements of a typical list page.\n|No.|Area|Description|Usage guidelines|\n|1|List|Displays records of the source table as rows and columns. Each row is a record, and the columns are fields. Define the list by adding a `repeater()` control within `area(Content)`, then add `field()` controls for the fields to display. See Work with repeater controls<devenv-repeater-controls>.|The order of the field controls determines their initial order on the page.|\n|2|Tile view|Displays records as tiles, also called bricks. Users can switch between list and tile views where available.<br /><br /> Define a `fieldgroup(Brick; <Field>)` in the source table to control which fields appear in tiles. A Brick field group isn't required for the client to display tiles.<br /><br /> See Displaying data as tiles<devenv-lists-as-tiles>.|Tiles are useful for records with media or images, such as customers, contacts, and items. See devenv-working-with-media-on-records.|\n|3|Action bar|Provides actions that open pages, run reports, or execute codeunits. Define the action bar in the actions section and individual actions with `action()` controls.<br /><br /> Actions can appear on menus such as Actions, Navigate, and Report, or in promoted categories. Arrange actions at the menu's top level or in groups. Pages opened from actions appear over the current page.<br /><br /> See devenv-adding-actions-to-a-page.|Include actions that users need for the task, such as posting, running a report, or opening related information. Place important actions at the top level and group closely related actions in submenus.|\n|4|Promoted actions|Promoted actions give selected actions a prominent place in the action bar. Define action references with actionref in `area(Promoted)`. Existing pages can also use the legacy Promoted-related properties on `action()` controls.<br /><br /> See devenv-promoted-actions.|Promote the actions that users need most often. Other actions remain available through the action bar's menus. Older action bar layouts use More options to show actions that aren't promoted.|\n|5|FactBoxes|The FactBox pane on the right side of a page contains vertically arranged parts. Each part can display content such as other pages, charts, or system parts.<br /><br /> Learn more about supported system parts, including Notes and Links, in devenv-adding-a-factbox-to-page#system-parts.|Use a FactBox for information related to the current record. For example, show sell-to customer sales history for the selected sales order.|\n|6|Search|A cross-column text search helps users narrow the records in a list. Standard list pages provide Search without additional code.<br /><br /> See Searching, filtering, and sorting data</ui-enter-criteria-filters>.||\n|7|Filter pane|Users can filter one or more fields to limit the records displayed. They can show or hide the filter pane as needed. See Searching, filtering, and sorting data</ui-enter-criteria-filters>.|The client provides the filter pane without extra code. You can define special words called filter tokens that users enter to filter records. See devenv-adding-filter-tokens.<br /><br /> FlowFilters let users adjust dimensions that influence calculated fields. They appear in the Filter totals by section. See devenv-flowfilter-overview.|\n> IMPORTANT\n> Use a single devenv-repeater-controls in the content area of a list page. If you include multiple repeaters or other controls, such as a group or grid<devenv-arrange-fields-in-rows-and-columns-using-gridlayout-control>, the page might not behave as expected. For pages that need other content controls, consider devenv-page-types-and-layouts#worksheet-page-layouts.\n## Behavior points<#tab/behavior>\n The properties/devenv-editable-property permits editing on a list page. Availability of Edit List also depends on ModifyAllowed, user permissions, and how the page is opened. Users can select Edit List to edit values across rows when editing is available.\n List pages that you access from the role center page open embedded within the role center framework. The pages always open in the read-only mode, regardless of the properties/devenv-editable-property property.\n List pages include system-provided actions, such as Show Attached and Open in Excel. The available actions depend on the page, client capabilities, and user permissions.\n Analysis mode is enabled by default on eligible list pages for users with the required permission. This setting doesn't mean pages open in analysis mode. To disable the ability, set the properties/devenv-analysismodeenabled-property to false.\n In Business Central online, Edit in Excel is available by default on eligible list pages for users with the required permissions. It isn't available for pages bound to temporary tables. On-premises environments require additional setup. See Controlling Edit in Excel on list pages<devenv-edit-in-excel-lists>.\n Tile views are useful for emphasizing record images and media. Images and media thumbnails aren't limited to tile view.\n## Developer tips<#tab/tips>\nFrom the user's perspective, a well-designed list page:\n Displays a single collection of entities or entries that the user needs for their work.\n Has a title that identifies the collection and the current view.\n Places important columns first and sets the properties/devenv-freezecolumn-property on the repeater control to identify the last frozen column. That column and all preceding columns remain visible when users scroll horizontally.\n Is accessible from relevant actions on the role center.\n Includes one or two FactBoxes to give necessary statistics and quick access to related documents.\n Promotes the actions that users need most often.\n> IMPORTANT\n> Use a single devenv-repeater-controls in the content area of a list page. If you include multiple repeaters or other controls, such as a group or grid<devenv-arrange-fields-in-rows-and-columns-using-gridlayout-control>, the page might not behave as expected. For pages that need other content controls, consider devenv-page-types-and-layouts#worksheet-page-layouts.\n## Designing for devices<#tab/targets>\nMobile devices generally display the same content as the web client. The layout adapts to the device and how users interact with it.\nYou can preview how your page will look on mobile devices directly in Designer.\n### Prioritize the visible columns\nDesign list pages to avoid having important columns on the far right of the column list. Assume you have no control over how many columns are displayed and consider that only the first few columns will be made visible.\n### Design for tile views\nOn phones, lists use tiles. Tablet layouts can also display rows and columns. Define a `fieldgroup(Brick; <Field>)` in the source table to choose which fields appear in tiles. Without a Brick field group, the client can use the DropDown field group or fall back to the first five columns. See devenv-field-groups.\n### Promote frequently used actions\nOnly promoted actions display on mobile devices, so promote the actions that are most useful to users. See devenv-promoted-actions.\n### Configure actions to display in shortcut menu on rows\nUse the properties/devenv-scope-action-property to configure actions in the shortcut menu on each row. This property is useful for actions related to a record, such as Line Comments.\n### Configure the gesture for actions\nUse the properties/devenv-gesture-property to configure the swipe direction for running actions on a device with a touch interface.\n## Related information\nAL development environment<devenv-reference-overview>\ndevenv-page-types-and-layouts\nPage extension object<devenv-page-ext-object>\ndevenv-actions-overview\nAdding pages and reports to search<devenv-al-menusuite-functionality>\nPersonalizing your workspace</ui-personalization-user>\nUse Designer<devenv-inclient-designer>"}