UI5X

UI5X

An OpenUI5 and SAPUI5 library of composite controls, with theming, accessibility and state handling built in.

Open the live demo to see every control and have fun customising how each one behaves.

The standard libraries stop at the building blocks, so anything composed from them gets rebuilt in every project. UI5X ships those compositions as controls, with the theming, accessibility and state handling already done.

Each one extends sap.ui.core.Control or the standard control it specialises. None of them touch a private API. You declare and bind them from XML views, JavaScript or TypeScript.

UI5X is in early development. APIs may change before version 1.0.

Features

• Skeleton — a placeholder in the shape of the content you are waiting for: a paragraph of lines, a block, or an avatar disc.
• LoadingContainer — swaps between a placeholder and the real content: bind loading to a model flag and it does the switch. Ships with a built-in skeleton and takes any control as a custom placeholder.
• LoadingResponsiveTable — wraps a responsive sap.m.Table and replaces its rows with matching skeleton cells, in a fixed or viewport-filling count.
• LoadingTable — the same for a grid sap.ui.table.Table, rendered as a presentation-only copy while data is loading.
• Accordion — groups AccordionItem sections with single or multiple expansion. Items take any UI5 control and can be disabled or held open.
• CopyButton — copies a value to the system clipboard and reports success or failure with a temporary icon, text and button type.
• SegmentedInput — collects numeric or alphanumeric identifiers in separate fields, with grouping, value-state feedback and paste support.
• ChatFeed — combines a message composer with a bindable conversation. Messages align by current user, group by date and expose edit or delete actions.
• Accessibility-aware — loading containers expose aria-busy, skeleton content is kept out of the accessibility tree, and animations respect prefers-reduced-motion. The interactive controls implement the UI5 focus and labelling contracts (getFocusDomRef, getIdForLabel, getAccessibilityInfo), so focus() and a sap.m.Label behave as they do on a standard control.
• Theme coverage — the sap_horizon and sap_fiori_3 families, each in light, dark and both high-contrast variants, with the right-to-left stylesheets generated alongside them. The high-contrast themes replace the subtle tints of the standard palettes so placeholders stay above the 3:1 contrast ratio instead of disappearing into the background.
• Verified on every change — the QUnit suite runs headless in CI against the lowest supported Node.js versions and the current LTS, together with the type check, the generated interfaces and a full library build.
• TypeScript first — written in TypeScript and shipped with type definitions, while remaining fully usable from JavaScript applications. Built with UI5 CLI 4 for OpenUI5 and SAPUI5.

Compatibility

• Developed against OpenUI5 1.151.0, and tested with SAPUI5 1.151.0 in SAP Business Application Studio. Older UI5 versions have not been validated yet
• Themes: sap_horizon, sap_horizon_dark, sap_horizon_hcb, sap_horizon_hcw, sap_fiori_3, sap_fiori_3_dark, sap_fiori_3_hcb, sap_fiori_3_hcw. Any other theme falls back to the base theme

Installation

npm install @raffaeledisomma/ui5x

1. In manifest.json, add two entries to the sap.ui5 section the application already has, as siblings of each other:

• dependencies.libs declares UI5X, so the runtime loads it with the component
• resourceRoots tells UI5 where the library is served from

{
  "sap.ui5": {
    "dependencies": {
      "libs": {
        "ui5x": {}
      }
    },
    "resourceRoots": {
      "ui5x": "./thirdparty/ui5x/"
    }
  }
}

2. TypeScript projects only — name the package in tsconfig.json:

{
  "compilerOptions": {
    "types": ["@openui5/types", "@raffaeledisomma/ui5x"]
  }
}

That is everything a locally previewed application needs. Before deploying it you have to add two build settings as well, described in Deploying an application that uses UI5X.

<script
  id="sap-ui-bootstrap"
  src="resources/sap-ui-core.js"
  data-sap-ui-resource-roots='{"ui5x": "/thirdparty/ui5x/"}'>
</script>

Deploying an application that uses UI5X

Nothing is needed for local preview: npm start serves the library from the dependency graph. For a deployment, add both of the following. For a SAP Fiori tools project they often belong in ui5-deploy.yaml rather than ui5.yaml, whichever configuration the build actually uses.

builder:
  settings:
    includeDependency:
      - ui5x
  customTasks:
    - name: ui5-task-zipper
      afterTask: generateCachebusterInfo
      configuration:
        includeDependencies: true

Checking that the library was deployed

Neither command changes anything. The first should print the matching line from the archive, the second a status line ending in 200:

unzip -l dist/<archive>.zip | grep "thirdparty/ui5x/library.js"
curl -sI https://<application-url>/thirdparty/ui5x/library.js | head -1

No output from grep means the archive was built without the library, so one of the two settings above is missing. A status other than 200 means the library never reached the server. A 200 means the deployment carries it, whether or not the application itself works.

Controls and API reference

One section per control: what it does, the full table of its properties, aggregations and events, then examples in JavaScript and in XML.

Skeleton

A Line skeleton stacks lines bars and shortens the last one to look like a paragraph; Rectangle fills the available width; Circle uses width as its diameter.

Examples

sap.ui.require(["ui5x/loading/Skeleton"], function (Skeleton) {
  new Skeleton({
    type: "Line",
    lines: 3,
    width: "20rem",
    animated: true
  }).placeAt("content");
});

In XML views:

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:loading="ui5x.loading">

  <loading:Skeleton type="Circle" width="3rem" />

</mvc:View>

LoadingContainer

A container that swaps between a placeholder and its real content: it renders the placeholder while loading is true, and its content otherwise. Only one of the two is in the DOM at a time, so loading can be bound directly to a model flag.

Examples

sap.ui.require([
  "ui5x/loading/LoadingContainer",
  "sap/m/Text"
], function (LoadingContainer, Text) {
  const oContainer = new LoadingContainer({
    loading: true,
    skeletonType: "Line",
    skeletonLines: 3,
    content: new Text({ text: "Loaded content" })
  });

  oContainer.placeAt("content");

  // later, when data has arrived
  oContainer.setLoading(false);
});

With a custom placeholder:

<loading:LoadingContainer
  loading="{ui>/busy}"
  xmlns:loading="ui5x.loading"
  xmlns:m="sap.m">

  <loading:placeholder>
    <loading:Skeleton
      type="Rectangle"
      width="20rem" />
  </loading:placeholder>

  <m:Text text="Loaded content" />

</loading:LoadingContainer>

LoadingResponsiveTable

LoadingResponsiveTable wraps a sap.m.Table. While loading is true, it renders a matching table with cloned columns and skeleton cells; when loading finishes, it renders the original table and its bound items.

Fixed mode always renders skeletonRows. Fill mode calculates how many rows fit between the table and the bottom of the viewport, using skeletonRows as the initial fallback and maxSkeletonRows as the upper limit.

Example

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:loading="ui5x.loading"
  xmlns:m="sap.m">

  <loading:LoadingResponsiveTable
    loading="{ui>/busy}"
    skeletonRowsMode="Fill"
    skeletonRows="5"
    maxSkeletonRows="20"
    dynamicSkeletonWidths="true">

    <m:Table items="{/rows}">
      <m:columns>
        <m:Column>
          <m:Text text="Name" />
        </m:Column>
        <m:Column>
          <m:Text text="Company" />
        </m:Column>
      </m:columns>

      <m:items>
        <m:ColumnListItem>
          <m:cells>
            <m:Text text="{name}" />
            <m:Text text="{company}" />
          </m:cells>
        </m:ColumnListItem>
      </m:items>
    </m:Table>

  </loading:LoadingResponsiveTable>

</mvc:View>

LoadingTable

LoadingTable provides the same loading experience for a grid sap.ui.table.Table. While loading is true, it renders an internal table with matching columns and skeleton rows. The original table, its row binding and its application data remain untouched.

Fixed mode always renders skeletonRows. Fill mode calculates how many rows fit between the table and the bottom of the viewport, using skeletonRows as the initial fallback and maxSkeletonRows as the upper limit.

Example

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:loading="ui5x.loading"
  xmlns:m="sap.m"
  xmlns:t="sap.ui.table">

  <loading:LoadingTable
    loading="{ui>/busy}"
    skeletonRowsMode="Fixed"
    skeletonRows="5"
    maxSkeletonRows="20"
    dynamicSkeletonWidths="true">

    <t:Table
      rows="{/rows}"
      visibleRowCount="5"
      visibleRowCountMode="Fixed">

      <t:columns>
        <t:Column width="15rem">
          <m:Label text="Customer" />
          <t:template>
            <m:Text text="{name}" />
          </t:template>
        </t:Column>

        <t:Column width="13rem">
          <m:Label text="Company" />
          <t:template>
            <m:Text text="{company}" />
          </t:template>
        </t:Column>
      </t:columns>

    </t:Table>

  </loading:LoadingTable>

</mvc:View>

Accordion

Accordion displays a collection of expandable AccordionItem sections. By default, expanding one item collapses the other toggleable items. Set multipleExpansion to true to allow several sections to remain open at the same time.

Example

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:layout="ui5x.layout"
  xmlns:m="sap.m">

  <layout:Accordion
    width="30rem"
    multipleExpansion="false"
    itemToggle=".onItemToggle">

    <layout:AccordionItem
      title="General information"
      expanded="true">
      <m:Text text="Content of the first section" />
    </layout:AccordionItem>

    <layout:AccordionItem title="Details">
      <m:VBox>
        <m:Label
          text="Company name"
          labelFor="companyName" />
        <m:Input
          id="companyName"
          value="{/company/name}"
          width="100%" />
        <m:HBox class="sapUiSmallMarginTop">
          <m:Button
            text="Save"
            type="Emphasized"
            press=".onSave" />
          <m:Button
            text="Cancel"
            press=".onCancel"
            class="sapUiTinyMarginBegin" />
        </m:HBox>
      </m:VBox>
    </layout:AccordionItem>

    <layout:AccordionItem
      title="Always expanded"
      expanded="true"
      toggleable="false">
      <m:Text text="This section cannot be collapsed" />
    </layout:AccordionItem>

  </layout:Accordion>

</mvc:View>

CopyButton

CopyButton extends sap.m.Button with clipboard support and visual success feedback. The feedback is shown only after the value has been copied successfully, then the original icon, text and button type are restored automatically.

When successType or errorType is omitted, the button keeps its current type. Set successIcon or errorIcon to an empty string to keep the original icon during feedback.

Clipboard access requires a secure context and a press initiated by the user, and the write is asynchronous, so it can fail after the press succeeded. The failure shows on the button and reaches the application through copyError; without either, a copy that never happened looks exactly like one that did.

Examples

sap.ui.require(["ui5x/button/CopyButton"], function (CopyButton) {
  new CopyButton({
    value: "npm i @raffaeledisomma/ui5x",
    text: "Copy",
    successText: "Copied",
    successType: "Accept"
  }).placeAt("content");
});

In XML views:

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:button="ui5x.button">

  <button:CopyButton
    value="{invoice>/id}"
    text="Copy ID"
    successText="Copied"
    successType="Accept" />

</mvc:View>

SegmentedInput

SegmentedInput collects a fixed-length value in individual fields. It supports numeric codes such as PINs and one-time passwords, as well as alphanumeric identifiers such as fiscal codes, license keys, VINs and IBANs. Pasted content is distributed across the segments automatically.

The exposed value is always a string, including in Numeric mode, so leading zeroes are preserved. Medium matches the standard sap.m.Input height; Small is suitable for compact forms and Large emphasizes short verification codes.

Examples

sap.ui.require(["ui5x/input/SegmentedInput"], function (SegmentedInput) {
  new SegmentedInput({
    segmentCount: 16,
    inputType: "Alphanumeric",
    size: "Small",
    showClearIcon: true,
    complete: function (oEvent) {
      this.setValueState("Success");
      this.setValueStateText(`Completed: ${oEvent.getParameter("value")}`);
    }
  }).placeAt("content");
});

In XML views:

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:input="ui5x.input">

  <input:SegmentedInput
    segmentCount="6"
    inputType="Numeric"
    size="Large"
    showSeparators="true"
    separatorInterval="3"
    value="{/verificationCode}"
    valueState="{/codeState}"
    valueStateText="{/codeStateText}"
    liveChange=".onCodeChange"
    complete=".onCodeComplete" />

</mvc:View>

ChatFeed

ChatFeed combines a growing sap.m.TextArea composer with a chat-style message list. Its default messages aggregation accepts ChatMessage controls and can be bound directly to a model. Set ownMessage on each message to align messages from the current user to the end side.

When sendOnEnter is enabled, Enter sends the message and Shift+Enter inserts a new line. When it is disabled, Enter keeps the standard multiline text-area behavior.

The control emits actions and leaves model mutations to the application, so the same API works with JSONModel, OData and other UI5 models. Sending clears the composer after the send event. Message appearance is configured independently for own and incoming messages. Conversation uses a transparent surface, while Bubble uses a neutral Fiori bubble. Bottom alignment preserves chronological order while initially showing the latest messages.

Examples

sap.ui.require([
  "ui5x/chat/ChatFeed",
  "ui5x/chat/ChatMessage"
], function (ChatFeed, ChatMessage) {
  const oChatFeed = new ChatFeed({
    value: "{/draft}",
    placeholder: "Write a message",
    sendOnEnter: true,
    sendButtonText: "Send",
    groupByDate: true,
    messageTimestampFormat: "Time",
    ownMessageAppearance: "Bubble",
    incomingMessageAppearance: "Conversation",
    composerPosition: "Bottom",
    messageAlignment: "Bottom",
    height: "100%",
    send: function (oEvent) {
      // Add oEvent.getParameter("value") to the application model.
    },
    messageEdit: function (oEvent) {
      // Update oEvent.getParameter("message").getBindingContext().
    },
    messageDelete: function (oEvent) {
      // Remove the corresponding entry from the application model.
    }
  });

  oChatFeed.bindAggregation("messages", {
    path: "/messages",
    template: new ChatMessage({
      key: "{id}",
      text: "{text}",
      sender: "{sender}",
      ownMessage: "{ownMessage}",
      editable: "{editable}",
      deletable: "{deletable}",
      timestamp: "{timestamp}"
    }),
    templateShareable: false
  });
});

<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:chat="ui5x.chat">

  <chat:ChatFeed
    value="{/draft}"
    placeholder="Write a message"
    sendOnEnter="true"
    groupByDate="true"
    messageTimestampFormat="Time"
    ownMessageAppearance="Bubble"
    incomingMessageAppearance="Conversation"
    composerPosition="Bottom"
    messageAlignment="Bottom"
    height="100%"
    messages="{/messages}"
    send=".onSend"
    messageEdit=".onMessageEdit"
    messageDelete=".onMessageDelete">

    <chat:messages>
      <chat:ChatMessage
        key="{id}"
        text="{text}"
        sender="{sender}"
        ownMessage="{ownMessage}"
        editable="{editable}"
        deletable="{deletable}"
        timestamp="{timestamp}" />
    </chat:messages>

  </chat:ChatFeed>

</mvc:View>

Development

Requires Node.js 20.19+ or 22.12+ and npm 8+. UI5 CLI 4 itself accepts Node.js 20.11+, but the interface generator loads an ESM-only dependency and require() of an ES module needs those versions. Node.js 21 is not supported by UI5 CLI 4.

npm install
npm start

npm start regenerates the control interfaces in watch mode and serves one manual demo page per control at http://localhost:8080/test-resources/ui5x/Skeleton.html. Each carries a toolbar that changes the layout and the behaviour of its control, and a theme selector covering every theme the library ships, which is the practical way to look at the dark and high-contrast palettes.

Controls are written in TypeScript under src/ui5x/, grouped by namespace, with the LESS sources in src/ui5x/themes/ and the tests in test/ui5x/. After changing control metadata (properties, aggregations, events), run npm run interfaces so the generated *.gen.d.ts declarations stay in sync.

Contributing

Issues and pull requests are welcome at github.com/rdisomma/ui5x. Please run npm run typecheck and the QUnit suite before opening a PR.

License

Apache-2.0 — see LICENSE.