1---2name: ui5-best-practices-tables3description: UI5 table best practices for freestyle applications. Use when creating/troubleshooting any table: sap.m.Table (ResponsiveTable), sap.ui.table.Table (GridTable), TreeTable, SmartTable, or sap.ui.mdc.Table. Covers control selection matrix, mandatory rules, common errors, and per-control API guidance. Triggers: "create a table", "which table should I use", "GridTable", "ResponsiveTable", "TreeTable", "SmartTable", "MDC table", "sap.ui.mdc.Table", "table not showing data", "table binding", "table selection", "drag and drop table", "table personalization", "table growing", "table pop-in", "table performance", "table export", "table sticky header". Keywords: sap.m.Table, sap.ui.table, GridTable, ResponsiveTable, TreeTable, SmartTable, sap.ui.mdc.Table, rows, items, rowMode, growing, sticky, personalization, p13n.Engine, DragDropInfo, OData V4, OData V2, ariaLabelledBy, cell templates4---56# UI5 Table Best Practices78Apply these guidelines whenever generating, reviewing, or troubleshooting UI5 table code in freestyle applications.910**UI5 version baseline:** SAPUI5 1.136+ LTS. All features mentioned are available from this version unless noted.1112## When to load each reference1314| Trigger | Load |15|---|---|16| Working on or planning a `sap.m.Table` (ResponsiveTable) | [`references/sap-m-table.md`](references/sap-m-table.md) |17| Working on or planning a `sap.ui.table.Table` (GridTable) | [`references/grid-table.md`](references/grid-table.md) |18| Working on or planning a `sap.ui.table.TreeTable` | [`references/tree-table.md`](references/tree-table.md) |19| Working on or planning a `sap.ui.comp.smarttable.SmartTable` | [`references/smart-table.md`](references/smart-table.md) |20| Working on or planning a `sap.ui.mdc.Table` | [`references/mdc-table.md`](references/mdc-table.md) |21| Adding drag-and-drop to any table | [`references/drag-and-drop.md`](references/drag-and-drop.md) |22| Adding column personalization | [`references/personalization.md`](references/personalization.md) |23| Choosing cell templates, alignment, or data type binding | [`references/cell-templates.md`](references/cell-templates.md) |2425Load before producing any output. Do not work from memory.2627---2829## Core Rules3031### Mandatory3233- Choose the table type using the [Selection Matrix](#selection-matrix) before writing any code.34- Use the `rows` aggregation for `sap.ui.table.*` and `items` for `sap.m.Table`. Never swap them.35- Use `sap.m.p13n.Engine` for personalization. Never build custom personalization dialogs.36- Set `ariaLabelledBy` on every table, referencing the table title control.37- Align cell content by data type: numbers and dates right (`hAlign="End"`), text and links left.38- Use appropriate cell templates: `sap.m.Text` for display, `sap.m.ObjectNumber` for numbers, `sap.m.Link` for navigation.39- Request `$count=true` from the back end for `sap.ui.table.*` when a total count is required.40- Use the `rowMode` aggregation (not the deprecated `visibleRowCountMode` property) for `sap.ui.table.*` (UI5 1.119+).4142### Prohibitions4344- Do not use global variables. Use `sap.ui.define` AMD modules or ES6 imports.45- Do not enable text wrapping in `sap.ui.table.*` cells — it breaks virtualization.46- Do not assume `sap.ui.export.Spreadsheet` is available. Detect the library before use.47- Do not use `sap.ui.table.Table` for mobile-first scenarios. Use `sap.m.Table`.48- Do not use `sap.m.Table` for datasets with 1000+ rows that require virtualization.49- Do not place multiple interactive elements in one `sap.ui.table.Table` cell.50- Do not return enum objects from formatters. Return string literals or primitive values.51- Do not use formatters for `ColumnListItem` `highlight`. Use direct data binding.52- Do not access models without checking availability — causes "Cannot read properties of undefined".53- Do not mix type namespaces: never use `sap.ui.model.odata.type.*` with a JSON model, or `sap.ui.model.type.*` with OData.5455### OData V4 policy5657Prefer SAP Fiori elements building blocks over freestyle tables for OData V4. Use `sap.ui.mdc.Table` only when Fiori elements is out of scope.5859---6061## Selection Matrix6263| Table type | Use when | Do not use when |64|---|---|---|65| `sap.m.Table` | Mobile/responsive, pop-in behavior, JSON models, fewer than 100 rows | 1000+ rows, virtualization required, desktop-only, cell selection needed |66| `sap.ui.table.Table` | Desktop, 1000+ rows, virtualization, fixed columns, dense data | Mobile-first, pop-in required, text wrapping, small datasets |67| `sap.ui.table.TreeTable` | Hierarchical data, expand/collapse, parent-child relationships | Flat data, mobile-first, grouping (not hierarchy) |68| `SmartTable` | OData V2, annotations, automatic columns, smart filtering | JSON-only, precise control required, OData V4 |69| `sap.ui.mdc.Table` | OData V4 freestyle (when Fiori elements is ruled out), delegate pattern | JSON-only, simple apps, OData V2 |7071### Dataset size guide7273| Rows | Recommended table | Strategy |74|---|---|---|75| < 100 | `sap.m.Table` | Simple binding, `growing` optional |76| 100–1000 | `sap.ui.table.Table` | Virtualization, `threshold=100` |77| 1000+ | `sap.ui.table.Table` | Virtualization, `threshold=100–500`, `$count=true` when needed |7879---8081## Common Errors8283| Symptom | Cause | Fix |84|---|---|---|85| No data displayed | Incorrect binding path or missing model | Verify `bindRows`/`bindItems` path and model attachment. |86| Rows not scrolling (`sap.ui.table.*`) | Count not requested | Set `$count=true` for OData when a total count is required. |87| 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. |88| Text wrapping issues | Wrapping enabled in `sap.ui.table.*` | Use fixed-height content or switch to `sap.m.Table`. |89| Copy/paste not working | Plugin not attached or wrong namespace | Attach the correct plugin (see Drag & Drop section). |90| Personalization not persisting | Engine not configured | Verify `sap.m.p13n.Engine` registration. |91| `CopyProvider` error | `extractData` not defined | Implement `extractData` on the plugin. |92| Table not visible | Invalid container structure | Use a valid container (see Container Structures). |93| 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. |94| Excel export fails silently | Library not loaded or invalid `extractData` | Detect the library, return a 2D array from `extractData`, ensure `dataSource` binding. |95| "No Data Available" | Model not set before binding | Set the model in `Component.init()` before router initialization. |9697---9899## Container Structures100101### Valid102103| Structure | Use case |104|---|---|105| `View > Page > content > Table` | Standard page |106| `View > Page > content > Panel > Table` | Grouped content |107| `View > Page > content > IconTabBar > items > IconTabFilter > Table` | Tabs |108| `View > SplitApp > detailPages > Page > Table` | Master-detail |109| `View > Dialog > content > Table` | Modal |110| `View > Table` | Standalone |111112### Invalid (and why)113114| Structure | Issue |115|---|---|116| `Page > content > VBox > Table` | `VBox` needs explicit height — table becomes invisible |117| `Page > VBox > Table` | `VBox` not in `content` — table not rendered |118| `Page > content > FlexBox > Table` | Sizing conflict — table collapses |119| `Page > content > ScrollContainer > Table` | Double scrolling — virtualization breaks |120121---122123## Performance & Accessibility124125### Anti-patterns to avoid126127- Handcrafted personalization dialogs (use `sap.m.p13n.Engine`).128- Text wrapping in `sap.ui.table.Table` cells.129- Multiple interactive elements in one GridTable cell.130- Mixing OData V2 `SmartTable` with V4 services.131- Deep nesting in cell templates.132- Fixed `threshold` without load testing.133- Unconditional `$count=true` (request count only when needed).134135### Accessibility checklist136137- Set `ariaLabelledBy` on every table, referencing the visible title.138- Use `sap.m.Text` (not raw text nodes) as cell templates.139- For `sap.ui.table.Table`: test keyboard navigation (Tab, arrow keys, Space/Enter for selection).140- Verify that the personalization dialog is keyboard-operable.141- Test with a screen reader (NVDA/JAWS on Windows, VoiceOver on macOS) before shipping.
ui5