Refactor branding preference fetching logic

.changeset/cold-games-lead.md

@@ -0,0 +1,6 @@
+---
+'@asgardeo/javascript': minor
+'@asgardeo/react': minor
+---
+
+Set default branding preference API call to false

packages/javascript/src/api/getBrandingPreference.ts

@@ -18,6 +18,9 @@
 
 import AsgardeoAPIError from '../errors/AsgardeoAPIError';
 import {BrandingPreference} from '../models/branding-preference';
+import {Platform} from '../models/platforms';
+import identifyPlatform from '../utils/identifyPlatform';
+import logger from '../utils/logger';
 
 /**
  * Configuration for the getBrandingPreference request
@@ -155,6 +158,32 @@ const getBrandingPreference = async ({
     if (!response?.ok) {
       const errorText: string = await response.text();
 
+      const platform: Platform = identifyPlatform({baseUrl} as any);
+
+      let errorDescription: string;
+      try {
+        const errorBody: {description?: string; message?: string} = JSON.parse(errorText) as {
+          description?: string;
+          message?: string;
+        };
+        errorDescription = errorBody?.description || errorBody?.message || errorText;
+      } catch {
+        errorDescription = errorText;
+      }
+
+      let platformConsoleGuidance: string;
+      if (platform === Platform.Asgardeo) {
+        platformConsoleGuidance = 'configure branding preferences in the Asgardeo console';
+      } else if (platform === Platform.IdentityServer) {
+        platformConsoleGuidance = 'configure branding preferences in the WSO2 Identity Server console';
+      } else {
+        platformConsoleGuidance = 'configure branding preferences in the platform console';
+      }
+
+      logger.warn(
+        `[BrandingError] ${errorDescription} To resolve this issue, please ${platformConsoleGuidance}. If you want to suppress this warning and stop fetching branding preferences, set \`<AsgardeoProvider>\` -> \`preferences\` -> \`theme\` -> \`inheritFromBranding\` to false.`,
+      );
+
       throw new AsgardeoAPIError(
         `Failed to get branding preference: ${errorText}`,
         'getBrandingPreference-ResponseError-001',

packages/javascript/src/models/config.ts

@@ -351,7 +351,10 @@ export interface ThemePreferences {
    */
   direction?: 'ltr' | 'rtl';
   /**
-   * Inherit from Branding from WSO2 Identity Server or Asgardeo.
+   * Inherit branding from WSO2 Identity Server or Asgardeo.
+   * When set to `true`, the SDK will fetch and apply branding preferences from the server.
+   * Defaults to `false` — branding is not fetched unless explicitly enabled.
+   * @default false
    */
   inheritFromBranding?: boolean;
   /**

packages/react/src/contexts/Asgardeo/AsgardeoProvider.tsx

@@ -446,8 +446,8 @@ const AsgardeoProvider: FC<PropsWithChildren<AsgardeoProviderProps>> = ({
       return;
     }
 
-    // Enable branding by default or when explicitly enabled
-    const shouldFetchBranding: boolean = preferences?.theme?.inheritFromBranding !== false;
+    // Only fetch branding when explicitly enabled via preferences.theme.inheritFromBranding
+    const shouldFetchBranding: boolean = preferences?.theme?.inheritFromBranding === true;
 
     if (shouldFetchBranding && isInitializedSync && baseUrl && !hasFetchedBranding && !isBrandingLoading) {
       fetchBranding();
@@ -645,7 +645,7 @@ const AsgardeoProvider: FC<PropsWithChildren<AsgardeoProviderProps>> = ({
             brandingPreference={brandingPreference}
             isLoading={isBrandingLoading}
             error={brandingError}
-            enabled={preferences?.theme?.inheritFromBranding !== false}
+            enabled={preferences?.theme?.inheritFromBranding === true}
             refetch={refetchBranding}
           >
             <ThemeProvider