How Feature Toggles Work
August 3, 2026 ยท View on GitHub
Feature toggles in Simorgh are fetched on the server side (or client side).
The getInitialData fetch returns the toggle configurations from the BBC toggles API via the toggleContextProvider which passes the state of the toggles to the useToggle hook in Simorgh. The toggle configurations from the BBC toggles API are set as remote toggles in iSite.
Local toggle configs are global and configured for the application environment, whereas remote toggles in iSite are configured to be service specific.
Simorgh has 3 toggle config files for test, local and live environments. Remote toggles on iSite also take precendence over local toggles when the toggle response is fetched:
https://github.com/bbc/simorgh/blob/latest/src/app/lib/utilities/fetchToggles/index.ts#L48-L54
If a toggle is not configured in iSite or in the local toggle configs deployed with Simorgh, then the toggle value will default to false.
Warning
There are some cases where a toggle is configured in iSite (an entry is present in iSite) but may not have values configured. The fetched response overwrites the local config file via destructuring (see fetchToggles() ). However if no value is configured, the local config file values will be used.
E.g. The adsNonce toggle is a valid toggle on iSite with valid entries as of 28/11/2025. This toggle affects services listed as entries on iSite, but for services not present as entries there, the local config files will be used. This caused issues before as all config files set this value as true. See https://github.com/bbc/simorgh/pull/13338 for more details.
Feature toggles can be found in src/app/lib/config/toggles
Viewing the toggles response
The toggles response can be viewed here (for test, live). The Origin header must also be set.
Fetching toggles locally
By default, fetching toggles from iSite is not enabled on the local environment - it will just use the default values from the localConfig file. Note that this file is not service aware - it will set the same value for all services.
In cases where the toggles response needs to be tested/validated, the following commands can be run from ws-nextjs-app.
For toggles from Test iSite:
yarn dev:toggles:test
For toggles from Live iSite:
yarn dev:toggles:live
Both commands enable remote toggle fetching (FETCH_TOGGLES=true) and set the ctx-service-env header (via TOGGLES_SERVICE_ENV) so you can switch environments without a rebuild. When fetching toggles locally the response cache is bypassed, so every request re-fetches the latest toggles from the endpoint. Hot reloading continues to work with these commands.
Note
These commands set the environment variables inline, so there is no need to edit local.env.
Simorgh Application Toggles
| Toggle Name | Description | Toggle Value | Example |
|---|---|---|---|
account | Enable Account functionality and IDCTA config fetching | Pipe-separated list of services (local env) to enable account for | enabled: true, value: hindi|hausa |
ads | Display Advertisements on Front Pages | ||
articleLiteSiteLink | Display the link to the lite site on Article pages | ||
articlePortraitVideo | Display portrait video carousel on Article pages | ||
comscoreAnalytics | Capture Comscore Analytics | ||
enableFetchingToggles | Enable fetching toggle values from remote Toggles Config API for specified services | ||
eventTracking | Enable event tracking across the app | ||
homePageRadioSchedule | Display Radio Schedule on Home Pages | The section of the front page to display the schedule component | Features, Verticals, Section 1, Interactivity |
include | Display Include on Story (STY) Pages | ||
liveRadioSchedule | Display Radio Schedule on Live Radio Pages | ||
mostRead | Display Most Read | ||
mostPopularMedia | Display Most Popular Media (Most Watched) component on Media Asset (MAP) Pages | Number of most popular media items to display (integer between 1 and 20) | 10 |
nielsenAnalytics | Capture Nielsen Analytics in Australia on AMP pages | ||
preloadLeadImage | Display preload image tag on Story (STY) Pages | ||
preroll | Display Preroll Advertisements on Media Asset (MAP) Pages | ||
scriptLink | Display Script Switching link for services with variants | ||
variantCookie | Set variant cookie for services with variants | ||
adsNonce | Uses "enabled" to check service as a boolean and "value" as countries list | value is a coma separated countries | enabled: true, value: 'es,mx' |