UI5 MDC Controls Best Practices

Apply these guidelines whenever generating, reviewing, or troubleshooting MDC control code in freestyle applications using OData V4 services.

UI5 version baseline: SAPUI5 1.136+ LTS. All features mentioned are available from this version unless noted.

When to load each reference

Load before producing any output. Do not work from memory.

The Delegate Pattern

All MDC controls use a delegate to decouple the control from data-source-specific logic. App developers must:

1. Specify the delegate in XML: delegate="{name: 'my/app/delegate/MyDelegate', payload: {entitySet: 'Products'}}"
2. Implement the delegate module extending the appropriate base delegate
3. Override key methods (at minimum fetchProperties)

Base delegates for OData V4:

JSON model usage: MDC controls also work with JSON models. Extend the base delegates directly (sap/ui/mdc/TableDelegate, sap/ui/mdc/FilterBarDelegate) — not the OData V4 variants. See references/mdc-json-delegates.md for details.

PropertyInfo — the core metadata format returned by fetchProperties:

{
    key: "propertyName",        // Unique identifier (required)
    label: "Display Label",     // User-visible label (required)
    dataType: "sap.ui.model.odata.v4.type.String"  // Data type (required)
}

Core Rules

Mandatory

• Every MDC control requires a delegate property pointing to a valid module path.
• Implement fetchProperties in the delegate returning PropertyInfo[] with at minimum: key, label, dataType.
• Extend the appropriate OData V4 base delegate (see table above) for OData V4 services. For JSON/other models, extend the generic base delegate directly.
• Use p13nMode to enable personalization (Column, Sort, Filter, Group for Table; Item, Sort, Filter, Type for Chart; Item for FilterBar).
• Use sap.ui.mdc.condition.Condition.createCondition() to construct conditions programmatically.
• Use sap.ui.model.odata.v4.type.* types in PropertyInfo dataType field for OData V4 models. Use sap.ui.model.type.* with JSON models. Register types in the TypeMap.
• Set ariaLabelledBy on FilterBar and Chart for accessibility.
• Prefer Fiori elements building blocks over freestyle MDC. Use MDC only when Fiori elements is out of scope.
• Use get_api_reference MCP tool to verify control APIs. Use run_ui5_linter to validate code.

Prohibitions

• Do not use MDC controls with OData V2 models. Use Smart controls (sap.ui.comp) instead. MDC works with OData V4 and JSON models.
• Do not access inner controls directly (e.g., inner sap.chart.Chart or sap.m.Table). Use the delegate or MDC control's public API.
• Do not omit key from PropertyInfo objects (formerly name, now deprecated).
• Do not construct condition objects manually as plain JSON. Always use Condition.createCondition(operator, values).
• Do not skip delegate implementation for production code (built-in defaults are for demos only).
• Do not use inline styles or scripts (CSP compliance).
• Do not use global access (sap.ui.mdc.FilterBar). Use sap.ui.define or ES6 imports.

Selection Matrix

Common Errors

Performance & Accessibility

Anti-patterns to avoid

• Loading all PropertyInfo eagerly when only a subset is needed (return minimal set from fetchProperties).
• Not implementing updateBindingInfo (conditions are never applied to the data binding).
• Skipping p13nMode configuration (personalization features are disabled by default).
• Creating large delegate modules (split complex logic into helper modules loaded on demand).
• Using synchronous operations in delegate methods (all delegate methods should return Promises).

Accessibility checklist

• Set ariaLabelledBy on FilterBar referencing a visible title.
• Set ariaLabelledBy on Chart referencing a visible title.
• Verify keyboard navigation works for personalization dialogs.
• Test ValueHelp type-ahead and dialog with screen reader.
• Ensure all FilterFields have meaningful labels via PropertyInfo label.