docs

Using Native HTML in XML Views

With the sap.html library, you can write standard HTML tags directly inside XML views and freely mix them with regular OpenUI5 controls while staying within the OpenUI5 programming model (data binding, models, event handling).

Context

The sap.html library provides lightweight typed OpenUI5 control wrappers for native HTML elements. Elements are written with their native lowercase tag names (div, a, input, …) and inherit from sap.ui.core.Control, which allows them to be aggregated into other OpenUI5 controls wherever the respective aggregation allows it.

Note that it is the responsibility of the application developer to ensure valid HTML. With the exception of void elements (see the table below), the sap.html library does not enforce valid nesting of HTML tags.

Note:

The former approach of embedding native (X)HTML through the XHTML namespace (xmlns:html="http://www.w3.org/1999/xhtml") is deprecated as of OpenUI5 version 1.120. Use the sap.html library instead.

Procedure

  1. Add sap.html as a library dependency in your manifest.json:

        {
        "sap.ui5": {
            "dependencies": {
                "libs": { "sap.html": {} }
            }
        }
    }

  2. Declare the sap.html XML namespace in your view. You can choose any namespace name. In the following example, it is set as the default namespace for a native developer experience. Elements use their native lowercase tag names:

    <mvc:View
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:m="sap.m"
    xmlns="sap.html">
    ...
</mvc:View>

  3. Write native HTML and mix it freely with OpenUI5 controls:

    <mvc:View controllerName="my.app.Main"
    xmlns:mvc="sap.ui.core.mvc"
    xmlns:m="sap.m"
    xmlns="sap.html">
    
    <m:Panel headerText="Native HTML + UI5">
        <div class="myLayout">
            <h1>Welcome, {/userName}</h1>
            <p>You can mix native HTML with OpenUI5 controls:</p>
    
            <!-- an OpenUI5 control, nested inside native HTML -->
            <m:Button text="A UI5 Button" press=".onPress"/>
    
            <!-- native anchor with data binding; opens safely in a new tab -->
            <a href="{/docsUrl}" target="_blank">Open documentation</a>
    
            <!-- void tags must not have a closing tag -->
            <input type="datetime-local" value="{/when}"/>
        </div>
    </m:Panel>
</mvc:View>

You can also use the elements programmatically by importing the corresponding module from the sap.html library:

sap.ui.require(["sap/html/Div", "sap/html/A"], function (Div, A) {
    new Div({ children: [ new A({ href: "https://example.com", text: "Link" }) ] });
});

Note:

The imported modules are capitalized, as is customary for OpenUI5 control classes. In XML views, use the native lowercase tag names (for example, div and a).

Native HTML vs. the OpenUI5-Supported Subset

The sap.html library supports the vast majority of HTML elements and stays as close to native HTML as possible. In some cases, it intentionally deviates, mostly for security reasons or to integrate with the OpenUI5 rendering and model layer.

Note:

Different compatibility rules apply to the sap.html library than to other OpenUI5 libraries. To stay aligned with the evolving HTML specification, the mapping of HTML elements and attributes to OpenUI5 controls and properties may change in future versions.

The following table shows where sap.html behavior differs from native HTML:

Differences Between Native HTML and sap.html Behavior

</tr> </tr> </table> > ### Caution: > Our offering in `sap.html` assumes that styles are given "literally" and therefore can be trusted. Using data binding introduces a new risk that needs to be tackled by the developer using it. Unlike URL-bearing attributes such as `href`, the `style` attribute value is not validated by the `sap.html` library. A bound value could apply arbitrary styles, for example, a `background-image` URL pointing to an uncontrolled endpoint. To counter such risks, you could use a formatter that sanitizes the style retrieved from the model. > ### Note: > `sap.html` is a low-level building block. For most application UIs, prefer the higher-level OpenUI5 control libraries \(for example, `sap.m`\). Use `sap.html` when you need native HTML structure inside a view. HTML is especially powerful when building custom layouts such as flex grids. > > While ``, `
Topic Native HTML `sap.html` Behavior Why We Deviate
Unsafe / structural tags \(`script`, `style`, `iframe`, `object`, `embed`, `link`, `meta`, `base`, `audio`, `video`, `source`, `track`, `template`, `noscript`, `html`/`head`/`body`, …\) Available **Not provided** Security — these are the classic script/style/resource-loading injection vectors \(and are meaningless inside the OpenUI5 control tree\)
Inline event handlers \(`onclick`, `onerror`, …\) HTML attributes containing script Exposed as **OpenUI5 events**, never rendered as attributes Security — prevents inline-script injection and integrates with OpenUI5 event handling
URL attributes \(`href`, `src`, `action`, `formaction`, `cite`, `ping`, `poster`, …\) Any string Typed `sap.ui.core.URI`; validated against the `sap/base/security/URLListValidator`. Unsafe schemes are dropped. Security — blocks `javascript:`/`data:` XSS via `URLListValidator`
Allowed URL schemes Any \(`mailto:`, `tel:`, …\) Specific URLs and schemes must be allow-listed Follows the standard OpenUI5 URL allowlist; apps opt in to more schemes via `URLListValidator.add(...)`
`rel` on ``/`` with `target` opening a new context </td> Author-controlled `noopener` is automatically merged into `rel` if not present Security — prevents reverse tabnabbing \(existing `rel` tokens are preserved\)
`class` attribute HTML attribute Not a property; `class` maps to OpenUI5's **custom style classes** \(`addStyleClass`\) Integrates with OpenUI5's style-class management
`data-*` attributes HTML attributes Become OpenUI5 **`CustomData`** \(rendered to the DOM\) > ### Note: > Names starting with `data-sap-ui-` are reserved for framework purposes and cannot be used. Integrates with the OpenUI5 custom-data model
`contenteditable` attribute Global attribute, available on any element **Not provided** It opens a freeform DOM editing surface that cannot be reconciled with the OpenUI5 control tree
Enum-like attributes \(``, ``, …\) </td> Native string values Native values are used \(for example, `type="datetime-local"`\) Harmonizes with native HTML authoring. This deliberately diverges from the classic OpenUI5 capitalized-enum convention.
Void elements \(`
`, ``, ``, …\) 		Cannot have content Text/child content is rejected \(error in XML view\) Matches HTML void-element semantics
Inline text & mixed content Text nodes Inline text between children is preserved in the OpenUI5 control tree and allows for full *data binding* Mixed HTML/OpenUI5 and text content is allowed, but only within HTML elements defined declaratively in XMLViews. Not supported for programmatic usage of the `sap.html` library.
Child controls DOM children Every element has a default `children` aggregation for nesting OpenUI5 controls or more HTML HTML, web components, and OpenUI5 controls can be composed freely
Element `id` `id` attribute The OpenUI5 control ID is rendered as the DOM `id` Consistency with OpenUI5 ID handling
Theming / CSS Developers style the element via style classes The `sap.html` library ships **no** additional styles The HTML wrapper controls are intentionally unstyled. You can style them through your app's CSS/style classes.
This site is open source. Improve this page.