ui5-best-practices-tablesUI5 table best practices and authoritative development guidelines. Use when the user asks to "create a table", "add a table", "which table should I use", "implement sap.m.Table", "implement sap.ui.table", "GridTable", "ResponsiveTable", "TreeTable", "SmartTable", "MDC table", "sap.ui.mdc.Table", "sap.ui.comp.smarttable", "table not showing data", "table bin…
Independent GitHub snapshot · Automated classification · Original documentation governs
name: ui5-best-practices-tables description: | UI5 table best practices and authoritative development guidelines. Use when the user asks to "create a table", "add a table", "which table should I use", "implement sap.m.Table", "implement sap.ui.table", "GridTable", "ResponsiveTable", "TreeTable", "SmartTable", "MDC table", "sap.ui.mdc.Table", "sap.ui.comp.smarttable", "table not showing data", "table binding", "table selection", "drag and drop table", "table personalization", "copy paste table", "table export", "table sticky header", "table growing", "table pop-in", "table performance", "table accessibility", "table items binding", or is writing any UI5 freestyle application that includes a table control. Covers: control selection matrix, mandatory rules, common error patterns, and per-control API guidance for sap.m.Table, sap.ui.table.Table, sap.ui.table.TreeTable, sap.ui.comp.smarttable.SmartTable, and sap.ui.mdc.Table.
Apply these guidelines whenever generating, reviewing, or troubleshooting UI5 table code in freestyle applications.
UI5 version baseline: SAPUI5 1.136+ LTS. All features mentioned are available from this version unless noted.
| Trigger | Load |
|---|---|
Working on or planning a sap.m.Table (ResponsiveTable) | references/sap-m-table.md |
Working on or planning a sap.ui.table.Table (GridTable) | references/grid-table.md |
Working on or planning a sap.ui.table.TreeTable | references/tree-table.md |
Working on or planning a sap.ui.comp.smarttable.SmartTable | references/smart-table.md |
Working on or planning a sap.ui.mdc.Table | references/mdc-table.md |
| Adding drag-and-drop to any table | references/drag-and-drop.md |
| Adding column personalization | references/personalization.md |
| Choosing cell templates, alignment, or data type binding | references/cell-templates.md |
Load before producing any output. Do not work from memory.
rows aggregation for sap.ui.table.* and items for sap.m.Table. Never swap them.sap.m.p13n.Engine for personalization. Never build custom personalization dialogs.ariaLabelledBy on every table, referencing the table title control.hAlign="End"), text and links left.sap.m.Text for display, sap.m.ObjectNumber for numbers, sap.m.Link for navigation.$count=true from the back end for sap.ui.table.* when a total count is required.rowMode aggregation (not the deprecated visibleRowCountMode property) for sap.ui.table.* (UI5 1.119+).sap.ui.define AMD modules or ES6 imports.sap.ui.table.* cells — it breaks virtualization.sap.ui.export.Spreadsheet is available. Detect the library before use.sap.ui.table.Table for mobile-first scenarios. Use sap.m.Table.sap.m.Table for datasets with 1000+ rows that require virtualization.sap.ui.table.Table cell.ColumnListItem highlight. Use direct data binding.sap.ui.model.odata.type.* with a JSON model, or sap.ui.model.type.* with OData.Prefer SAP Fiori elements building blocks over freestyle tables for OData V4. Use sap.ui.mdc.Table only when Fiori elements is out of scope.
| Table type | Use when | Do not use when |
|---|---|---|
sap.m.Table | Mobile/responsive, pop-in behavior, JSON models, fewer than 100 rows | 1000+ rows, virtualization required, desktop-only, cell selection needed |
sap.ui.table.Table | Desktop, 1000+ rows, virtualization, fixed columns, dense data | Mobile-first, pop-in required, text wrapping, small datasets |
sap.ui.table.TreeTable | Hierarchical data, expand/collapse, parent-child relationships | Flat data, mobile-first, grouping (not hierarchy) |
SmartTable | OData V2, annotations, automatic columns, smart filtering | JSON-only, precise control required, OData V4 |
sap.ui.mdc.Table | OData V4 freestyle (when Fiori elements is ruled out), delegate pattern | JSON-only, simple apps, OData V2 |
| Rows | Recommended table | Strategy |
|---|---|---|
| < 100 | sap.m.Table | Simple binding, growing optional |
| 100–1000 | sap.ui.table.Table | Virtualization, threshold=100 |
| 1000+ | sap.ui.table.Table | Virtualization, threshold=100–500, $count=true when needed |
| Symptom | Cause | Fix |
|---|---|---|
| No data displayed | Incorrect binding path or missing model | Verify bindRows/bindItems path and model attachment. |
Rows not scrolling (sap.ui.table.*) | Count not requested | Set $count=true for OData when a total count is required. |
Selection not working (sap.ui.table.*) | Plugin conflict | Do not call the table selection API when a selection plugin is applied; use the plugin API instead. |
| Text wrapping issues | Wrapping enabled in sap.ui.table.* | Use fixed-height content or switch to sap.m.Table. |
| Copy/paste not working | Plugin not attached or wrong namespace | Attach the correct plugin (see Drag & Drop section). |
| Personalization not persisting | Engine not configured | Verify sap.m.p13n.Engine registration. |
CopyProvider error | extractData not defined | Implement extractData on the plugin. |
| Table not visible | Invalid container structure | Use a valid container (see Container Structures). |
| OData types on JSON model | Wrong type namespace | Match the type namespace to the model: sap.ui.model.type.* for JSON, sap.ui.model.odata.type.* for OData V2, sap.ui.model.odata.v4.type.* for OData V4. |
| Excel export fails silently | Library not loaded or invalid extractData | Detect the library, return a 2D array from extractData, ensure dataSource binding. |
| "No Data Available" | Model not set before binding | Set the model in Component.init() before router initialization. |
| Structure | Use case |
|---|---|
View > Page > content > Table | Standard page |
View > Page > content > Panel > Table | Grouped content |
View > Page > content > IconTabBar > items > IconTabFilter > Table | Tabs |
View > SplitApp > detailPages > Page > Table | Master-detail |
View > Dialog > content > Table | Modal |
View > Table | Standalone |
| Structure | Issue |
|---|---|
Page > content > VBox > Table | VBox needs explicit height — table becomes invisible |
Page > VBox > Table | VBox not in content — table not rendered |
Page > content > FlexBox > Table | Sizing conflict — table collapses |
Page > content > ScrollContainer > Table | Double scrolling — virtualization breaks |
sap.m.p13n.Engine).sap.ui.table.Table cells.SmartTable with V4 services.threshold without load testing.$count=true (request count only when needed).ariaLabelledBy on every table, referencing the visible title.sap.m.Text (not raw text nodes) as cell templates.sap.ui.table.Table: test keyboard navigation (Tab, arrow keys, Space/Enter for selection).