A composite control is an OpenUI5 control whose visual representation is built by reusing other controls, providing a stable public API while encapsulating implementation details.
Examples for composite controls are a search field that combines an input and a button, or a layout container that arranges its children inside an inner VBox. From the outside, a composite has its own properties, events, and aggregations. From the inside, it delegates rendering and behavior to the controls it is composed of.
Because the inner controls are an implementation detail, the control developer can change the composition later — adding controls, replacing one with another, or even removing the composition entirely — without breaking applications that use the composite.
Note:
If you do not intend to re-use a control in several places, a composite control may not be your best choice. Composite controls are best suited for (massive) re-use and for a public API that shields the application developer from its inner workings. If these are not your requirements, consider using other techniques of factoring out common parts within your application. You can, for example, simply write an XML fragment or a function returning the root of some control tree.
Reach for a composite when you need a stable public API that is consumed by several applications or several places in one application. The encapsulation buys you the freedom to evolve its inner structure later. For one-shot factoring of repeated XML code inside a single application, a fragment or a small factory function is usually a better fit.
The pages in this Developer’s Guide section cover orthogonal aspects of a composite control. Pick the ones that match your need:
| Aspect | When do I need this? | Documentation |
|---|---|---|
| Define what your composite is built from and pass property changes to the inner controls | Always | [Building Standard Composite Controls](/docs/07_Developing_Controls/building-standard-composite-controls-c1512f6.html) |
| Let app developers add content into an aggregation of your composite | When you expose an aggregation that holds multiple children on your control's public API | [Forwarding Aggregations](/docs/07_Developing_Controls/forwarding-aggregations-64a5e17.html) |
| Let inner controls bind to your composite's properties instead of receiving them via setters | When you have many properties to keep in sync, or when migrating from `XMLComposite` | [Synchronizing Properties via a $this Model](/docs/07_Developing_Controls/synchronizing-properties-via-a-this-model-8b9014d.html) |
XMLComposite?sap.ui.core.XMLComposite is deprecated as of OpenUI5 version 1.88. There is no drop-in replacement; existing XMLComposite controls are migrated to the standard sap.ui.core.Control pattern documented in this section. For a broader overview of deprecated APIs and their replacements, see our Modernization Guide.
If you are migrating from XMLComposite, the recommended reading order is:
XMLComposite fragment uses {$this>...} bindings.XMLComposite exposes aggregations.The following table summarizes what XMLComposite provides implicitly, what is no longer available after migration, and which page in this Developer’s Guide section covers the compensation:
| `XMLComposite` feature | What is lost | Compensation |
|---|---|---|
| Fragment-based UI definition | Declarative inner control tree | [Building Standard Composite Controls](/docs/07_Developing_Controls/building-standard-composite-controls-c1512f6.html) — imperative `init` plus an explicit renderer |
| Automatic `$this` model registration | Bidirectional property bindings between fragment and outer control | [Synchronizing Properties via a $this Model](/docs/07_Developing_Controls/synchronizing-properties-via-a-this-model-8b9014d.html) — the `$this` binding pattern |
| Implicit aggregation wiring inside the fragment | Fragment-based forwarding to inner aggregations | [Forwarding Aggregations](/docs/07_Developing_Controls/forwarding-aggregations-64a5e17.html) — same `forwarding` configuration on a hidden inner aggregation |
| `byId("foo")` for fragment children | Direct lookup of inner controls by fragment-local ID | Keep references on `this` directly, or compute the inner control's ID as `getId() + "-foo"` and look it up via `Element.getElementById(...)` — there is no `byId` method on a standard `Control`. For more information, see [Building Standard Composite Controls](/docs/07_Developing_Controls/building-standard-composite-controls-c1512f6.html). |
init, propagating property changes, and writing a renderer.Related Information
Building Standard Composite Controls
Synchronizing Properties via a $this Model