diff --git a/docs/2-advanced/01-configuration.md b/docs/2-advanced/01-configuration.md
index dd2bd817181a..83fdeeb18eea 100644
--- a/docs/2-advanced/01-configuration.md
+++ b/docs/2-advanced/01-configuration.md
@@ -20,6 +20,7 @@ There are several configuration settings that affect all UI5 Web Components glob
| [enableDefaultTooltips](#enableDefaultTooltips) | `true`, `false` | `true` | Whether to display default tooltips | Components (Icon, Button, RatingIndicator, etc.) |
| [timezone](#timezone) | `Asia/Tokyo`, `Pacific/Apia`, `Asia/Kolkata`, `Europe/Sofia` and etc. | Your local time zone. | Allows to override your local time zone. | Date/time components (`ui5-date-picker`, etc.) |
| [themeRoot](#themeRoot) | String to a URL - see the [themeRoot](#themeRoot) section below | N/A | Allows to set a URL to a Theme-designer-created custom theme. | All components |
+| [ignoreUrlParams](#ignoreUrlParams) | `true`, `false` | `false` | Whether to ignore URL parameters during configuration initialization | Framework |
### theme
@@ -304,6 +305,26 @@ or, the preferred new format:
Failing to do so will result in a warning in the console and the theme root will not be set.
+### ignoreUrlParams
+
+
+*Since 2.23.0*
+
+This configuration option controls whether URL parameters (e.g. `sap-ui-theme`, `sap-ui-language`, `sap-ui-animationMode`) are processed during framework initialization.
+
+By default, the framework reads `sap-*` and `sap-ui-*` URL parameters and uses them to override the configuration script settings. While useful during development and testing, production applications may prefer to disable this behavior to ensure consistent and predictable configuration.
+
+When set to `true`, all URL parameter processing is skipped and only the configuration script and module imports are used.
+
+Example:
+```html
+
+```
+
## Configuration Script
@@ -406,4 +427,10 @@ import { getTimezone } from "@ui5/webcomponents-base/dist/config/Timezone.js";
```js
import { getThemeRoot, setThemeRoot } from "@ui5/webcomponents-base/dist/config/ThemeRoot.js";
+```
+
+ - `ignoreUrlParams`
+
+```js
+import { getIgnoreUrlParams, setIgnoreUrlParams } from "@ui5/webcomponents-base/dist/config/UrlParams.js";
```
\ No newline at end of file
diff --git a/packages/base/cypress/specs/ConfigurationURL.cy.tsx b/packages/base/cypress/specs/ConfigurationURL.cy.tsx
index 6b615fda7e8c..8fcd3221a3b7 100644
--- a/packages/base/cypress/specs/ConfigurationURL.cy.tsx
+++ b/packages/base/cypress/specs/ConfigurationURL.cy.tsx
@@ -521,3 +521,57 @@ describe("Some settings can be set via SAP UI URL params", () => {
.should("equal", "sap_fiori_3_hcb");
});
});
+
+describe("URL parameters are ignored when ignoreUrlParams is set", () => {
+ before(() => {
+ const searchParams = "sap-ui-language=de&sap-ui-theme=sap_horizon_hcb&sap-ui-animationMode=none";
+
+ cy.stub(internals, "search").callsFake(() => {
+ return searchParams;
+ });
+
+ cy.window()
+ .then($el => {
+ const scriptElement = document.createElement("script");
+ scriptElement.type = "application/json";
+ scriptElement.setAttribute("data-ui5-config", "true");
+ scriptElement.innerHTML = JSON.stringify({
+ language: "fr",
+ animationMode: "basic",
+ ignoreUrlParams: true,
+ });
+ return $el.document.head.append(scriptElement);
+ });
+
+ cy.wrap({ resetConfiguration })
+ .invoke("resetConfiguration", true);
+
+ cy.mount();
+ });
+
+ after(() => {
+ cy.window()
+ .then($el => {
+ const scriptElement = $el.document.head.querySelector("script[data-ui5-config]");
+ scriptElement?.remove();
+ });
+ });
+
+ it("Tests that URL language param is ignored and script value is used", () => {
+ cy.wrap({ getLanguage })
+ .invoke("getLanguage")
+ .should("equal", "fr");
+ });
+
+ it("Tests that URL theme param is ignored", () => {
+ cy.wrap({ getTheme })
+ .invoke("getTheme")
+ .should("not.equal", "sap_horizon_hcb");
+ });
+
+ it("Tests that URL animationMode param is ignored and script value is used", () => {
+ cy.wrap({ getAnimationMode })
+ .invoke("getAnimationMode")
+ .should("equal", AnimationMode.Basic);
+ });
+});
diff --git a/packages/base/src/InitialConfiguration.ts b/packages/base/src/InitialConfiguration.ts
index b47f359fe177..ba70569adf05 100644
--- a/packages/base/src/InitialConfiguration.ts
+++ b/packages/base/src/InitialConfiguration.ts
@@ -24,6 +24,7 @@ type InitialConfig = {
fetchDefaultLanguage: boolean,
defaultFontLoading: boolean,
enableDefaultTooltips: boolean,
+ ignoreUrlParams: boolean,
};
let initialConfig: InitialConfig = {
@@ -40,6 +41,7 @@ let initialConfig: InitialConfig = {
fetchDefaultLanguage: false,
defaultFontLoading: true,
enableDefaultTooltips: true,
+ ignoreUrlParams: false,
};
/* General settings */
@@ -88,6 +90,11 @@ const getEnableDefaultTooltips = () => {
return initialConfig.enableDefaultTooltips;
};
+const getIgnoreUrlParams = () => {
+ initConfiguration();
+ return initialConfig.ignoreUrlParams;
+};
+
/**
* Get the configured calendar type
* @returns { String } the name of the configured calendar type
@@ -226,7 +233,9 @@ const resetConfiguration = (testEnv?: boolean) => {
parseConfigurationScript();
// 2. URL parameters overwrite configuration script parameters
- parseURLParameters();
+ if (!initialConfig.ignoreUrlParams) {
+ parseURLParameters();
+ }
// 3. If OpenUI5 is detected, it has the highest priority
applyOpenUI5Configuration();
@@ -246,4 +255,5 @@ export {
getDefaultFontLoading,
resetConfiguration,
getEnableDefaultTooltips,
+ getIgnoreUrlParams,
};
diff --git a/packages/base/src/config/UrlParams.ts b/packages/base/src/config/UrlParams.ts
new file mode 100644
index 000000000000..3bb34d6044a9
--- /dev/null
+++ b/packages/base/src/config/UrlParams.ts
@@ -0,0 +1,37 @@
+import { getIgnoreUrlParams as getConfiguredIgnoreUrlParams } from "../InitialConfiguration.js";
+
+let _ignoreUrlParams: boolean;
+
+/**
+ * Returns if the "ignoreUrlParams" configuration is set.
+ * @public
+ * @since 2.23.0
+ * @returns { boolean }
+ */
+const getIgnoreUrlParams = (): boolean => {
+ if (_ignoreUrlParams === undefined) {
+ _ignoreUrlParams = getConfiguredIgnoreUrlParams();
+ }
+
+ return _ignoreUrlParams;
+};
+
+/**
+ * Defines the "ignoreUrlParams" setting.
+ *
+ * - When set to "true", the framework will not process URL parameters
+ * (e.g. sap-ui-theme, sap-ui-language) during initialization.
+ * - When set to "false" (default), URL parameters are processed normally.
+ *
+ * @public
+ * @since 2.23.0
+ * @param { boolean } ignoreUrlParams
+ */
+const setIgnoreUrlParams = (ignoreUrlParams: boolean) => {
+ _ignoreUrlParams = ignoreUrlParams;
+};
+
+export {
+ getIgnoreUrlParams,
+ setIgnoreUrlParams,
+};
diff --git a/packages/base/src/index.ts b/packages/base/src/index.ts
index a73b95fd0f12..e0639895607e 100644
--- a/packages/base/src/index.ts
+++ b/packages/base/src/index.ts
@@ -24,6 +24,7 @@ import {
getFetchDefaultLanguage,
} from "./config/Language.js";
import { getNoConflict, setNoConflict } from "./config/NoConflict.js";
+import { getIgnoreUrlParams, setIgnoreUrlParams } from "./config/UrlParams.js";
import {
getTheme,
setTheme,
@@ -133,6 +134,8 @@ export {
getFetchDefaultLanguage,
getNoConflict,
setNoConflict,
+ getIgnoreUrlParams,
+ setIgnoreUrlParams,
getTheme,
setTheme,
getDefaultTheme,