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

I have an UI5-based app (1.66+), which works correctly, but there are huge empty spaces on the left and right sides of the screen (aka letterboxing is on):

Widescreen SAPUI5 app

I want to disable letterboxing to use the entire screen space.

I tried the following approaches so far:

  1. To use "fullWidth": true in sap.ui section of manifest.json
  2. To add desktop-related classes to the HTML-tag in index.html:
<html class="sap-desktop sapUiMedia-Std-Desktop sapUiMedia-StdExt-LargeDesktop">
  1. To add appWidthLimited: false to index.html:
    sap.ui.getCore().attachInit(function () {
        new sap.m.Shell({
            app: new sap.ui.core.ComponentContainer({
                height: "100%",
                name: "APPNAME"
            appWidthLimited: false

Just like it is described in «How to customise Shell container in SAPUI5».

But none of them works for me.

I succeeded to solve the issue via a static XML-template — just add <Shell id="shell" appWidthLimited="false"> to the main XML-template, but now I want to understand how to implement it via JS in new sap.m.Shell(…) definition.

The starting point for code experiments is below.


<!DOCTYPE html>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <script id="sap-ui-bootstrap"
            data-sap-ui-resourceroots='{"letterboxing.widescreen": "./"}'
    <body class="sapUiBody">
        <div data-sap-ui-component data-name="letterboxing.widescreen" data-id="container" data-settings='{"id" : "widescreen"}' id="content"></div>


], function (UIComponent, Device, models) {
    "use strict";

    return UIComponent.extend("letterboxing.widescreen.Component", {

        metadata: {
            manifest: "json"

        init: function () {
            // call the base component's init function
            UIComponent.prototype.init.apply(this, arguments);

            // enable routing

            // set the device model
            this.setModel(models.createDeviceModel(), "device");


  • 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 its appWidthLimited property accordingly.

    For example:

    SAP Web IDE searching in project

    In index.html or in a module assigned to data-sap-ui-on-init

    ], (Shell, ComponentContainer) => new Shell({
      appWidthLimited: false|true, // <-- default: true
      // ...

    In root view

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

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

    Note: if the letterboxing is not required, consider removing sap.m.Shell entirely. There is no real purpose of sap.m.Shell if the application always runs with full width or embedded in FLP.

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

    Apps on SAP Fiori launchpad (FLP)

    The app or component …:

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

    Statically in manifest.json

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

    Documentation: Descriptor for Applications, Components, and Libraries

    Dynamically at runtime

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

    According to SAP Fiori design guidelines, switching the letterbox state during runtime is allowed:

    Letterboxing can be switched on or off [...] for individual pages within an application. [...]

    In some cases, applications may need to have the flexibility to change the width at runtime for different views. [...] Apps can change the width in the AppConfiguration service at runtime for different views.

    * The API setApplicationFullWidth, however, is deprecated since UI5 1.120. If you really need switching the letterbox state during the application runtime, please create a new customer ticket at with the component CA-FLP-FE-UI.

    API reference:
    UX guideline: Letterboxing

    ⚡ Limitations

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

    • FLP on Cloud Foundry in BTP (Deployed apps running in an iframe). SAP is still looking into it.
      FIXED since SAPUI5 1.120.5
    • Apps generated via SAP Fiori elements — by design.