Ui5 Best Practices Smart Controls

UI5 Smart Controls Best Practices

Apply these guidelines whenever generating, reviewing, or troubleshooting UI5 smart control code in freestyle applications using OData V2 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.

Core Rules

Mandatory

• Always specify entitySet on Smart controls or ensure the control inherits a binding context that resolves the entity type.
• Use ControlConfiguration in XML for SmartFilterBar field overrides (control type, filter type, index). Only visible, label, and visibleInAdvancedArea can be changed at runtime.
• Use the correct hierarchy: SmartForm > Group > GroupElement > SmartField. Never place SmartFields directly in a SmartForm.
• Wait for the initialise event before programmatically accessing inner controls (e.g., getInnerControl(), getChart()).
• Use sap.ui.model.odata.type.* types in bindings alongside OData V2 models. Never use sap.ui.model.type.* with OData V2.
• Set ariaLabelledBy on SmartFilterBar and SmartChart referencing a visible title for accessibility.
• Use check() on SmartForm for client-side mandatory field validation before submitting data.
• Use get_api_reference MCP tool to verify control APIs. Use run_ui5_linter to validate code.

Prohibitions

• Do not use Smart controls with OData V4 services. Use MDC controls (sap.ui.mdc) instead.
• Do not set custom formatters on SmartField value property. SmartField manages its own rendering based on metadata. Use annotations to influence behavior.
• Do not use composite binding syntax (parts: [...]) on SmartField. It manages its own composite bindings for unit/currency fields.
• Do not call getChart() synchronously during initialization. Use the initialise event or getChartAsync().
• Do not directly modify inner controls of SmartChart or SmartTable (e.g., the inner sap.chart.Chart). Use the smart control's public API.
• Do not hardcode field labels. Use sap:label or @Common.Label annotations in OData metadata.
• Do not use inline styles or scripts in HTML (CSP compliance).
• Do not use global access (sap.ui.comp.smartfield.SmartField). Use sap.ui.define or ES6 imports.

Selection Matrix

Common Errors

Performance & Accessibility

Anti-patterns to avoid

• Requesting all value lists eagerly (use lazy loading; value lists load on-demand by default).
• Using liveMode="true" on SmartFilterBar with expensive backend queries (causes rapid re-fetching).
• Deep nesting of SmartForm groups (keep hierarchy flat: Form > Group > GroupElement).
• Bypassing SmartChart API to modify inner chart directly (breaks personalization and variant management).
• Not setting ignoredChartTypes when certain chart types are irrelevant (unnecessary UI options).

Accessibility checklist

• Set ariaLabelledBy on SmartFilterBar referencing a visible title.
• Set ariaLabelledBy on SmartChart referencing a visible title.
• SmartForm automatically propagates labels to SmartFields via annotations.
• Verify keyboard navigation works for SmartFilterBar "Adapt Filters" dialog.
• Test SmartLink popover with screen reader (navigation targets must be announced).