How to disable or enable letterboxing and adjust UI5 for the widescreen?

Ok, so there seems to be many similar questions regarding how to disable/enable letterboxing. This answer should provide a solution for each case:

Standalone Apps

Look for the instantiation of sap.m.Shell in your project and configure appWidthLimited accordingly.

For example:

SAP Web IDE searching in project

In index.html or index.js

sap.ui.require([
  "sap/m/Shell",
  "sap/ui/core/ComponentContainer",
], (Shell, ComponentContainer) => new Shell({
  appWidthLimited: false|true, // <--
  // ...
}).placeAt("content"));

In root view

<Shell xmlns="sap.m" appWidthLimited="false|true">
  <App>
    <!-- ... -->

Of course, the Shell can be configured dynamically in JS too with myShell.setAppWidthLimited.

Note: if the letterboxing is never required, please reconsider whether <Shell> in your app is necessary at all. There is no purpose of sap.m.Shell if the app is displayed always in full width.

API reference: sap.m.Shell
UX guideline: Letterboxing


Apps on SAP Fiori launchpad (FLP)

The component / app …:

  • should not contain sap.m.Shell anywhere (please check the root view).
  • launches from FLP instead (no index.html).

Statically in manifest.json

"sap.ui": {
  "fullWidth": true|false,
  ...
}, 

Dynamically in runtime

// AppConfiguration required from "sap/ushell/services/AppConfiguration"
AppConfiguration.setApplicationFullWidth(true|false);

API reference: sap.ushell.services.AppConfiguration
UX guideline: Letterboxing


⚡ Limitations

Currently, the static setting "fullWidth": false is not supported by:

  • FLP on Cloud Foundry (deployed apps running in an iframe). SAP is looking into it..
    The dynamic setting via sap/ushell/services/AppConfiguration can be used instead.
  • Apps generated via SAP Fiori elements – by design.

Leave a Comment