Customize full application embed

Customize full application embed

The Visual Embed SDK provides several controls to customize the embedded view, including setting the default landing page, navigation style, visibility of modules and menu items, and more.

UI experience modesπŸ”—

The ThoughtSpot application interface supports the following UI experience modes:

  • V3 experience Early Access
    Includes a sliding left navigation panel that dynamically adjusts its menu based on the application context. In this experience mode, the home page includes the same customizable modules as the V2 experience.

  • V2 experience
    Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context.

  • V1 Classic experience (Default experience)
    Includes a standard top navigation and a static home page with limited customization options.

V3 experienceπŸ”—

The V3 experience introduces the following changes:

  • Navigation and UI layout:

    • A redesigned top navigation bar with a modern and simplified layout.

    • Persona-based navigation with app selector icons. The app selection icons are organized into contextual sections, each with its own left navigation.

    • Admin settings in the user profile dropdown.

    • A hamburger menu for toggling left navigation.

      To customize the navigation experience, use the navigation attributes in the SDK.

  • Home page:
    The V3 experience includes a modular home page, similar to the V2 experience. You can customize the visibility and order of the home page components using the properties available in the SDK.

The following figure shows the UI layout in the V3 experience:

New home page

Enable V3 experienceπŸ”—

The V3 experience is an Early Access feature that ThoughtSpot administrators can enable at the instance level. It is disabled by default

When it is enabled on your ThoughtSpot instance, you can upgrade the UI experience in your embed using the discoveryExperience object in the SDK. This object supports the following properties:

  • primaryNavbarVersion
    Enables the V3 experience. The valid setting for the V3 experience is PrimaryNavbarVersion.Sliding.

  • homePage
    Enables a modular home page that is similar to the V2 modular home page experience. The supported value is HomePage.Modular.

import {
    AppEmbed, // Main class to embed the full ThoughtSpot app
    PrimaryNavbarVersion // Enum for V3 navigation experience
    HomePage, // Enum for home page experience settings
} from '@thoughtspot/visual-embed-sdk';

const embed = new AppEmbed("#embed", {
    // Enable V3 navigation and home page experience
    discoveryExperience: {
        primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enables V3 sliding navigation
        homePage: HomePage.Modular, // modular home page
    },
    // Show navigation panels
    showPrimaryNavbar: true,
    //... other view configuration attributes
});

V2 experienceπŸ”—

The V2 experience provides the following features:

  • Navigation experience:

    • The top navigation includes an app selector menu, which consists of different persona-based menu elements to allow users to switch between different application contexts.

    • Each application context has its own left navigation menu.

      You can customize the navigation experience using the navigation controls available in the SDK.

  • Home page experience:
    The home page includes customizable modules such as watchlist, favorites, library, trending charts, and more. You can customize the visibility and order of the home page components using the properties available in the SDK.

Using the V2 experienceπŸ”—

The V2 experience is disabled by default on ThoughtSpot embedding applications. Setting modularHomeExperience to true in the SDK enables the V2 experience.

const embed = new AppEmbed("#embed", {
    // Enable the V2 experience
    modularHomeExperience: true,
    //... other view config attributes
});
Note

The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features.

Customize navigation experienceπŸ”—

The Visual Embed SDK provides several parameters to hide or customize navigation controls.

Customize top navigationπŸ”—

The top navigation menu bar (classic experience), app selector the app switcher menu (V2 experience), and left navigation panel on the home page (V3 experience) are hidden by default in the embedded view. To show these elements in the embedded view, set showPrimaryNavbar to true.

If the navigation panel is visible in the embedded view, you can use the following customization settings in the SDK:

  • hideOrgSwitcher
    To show or hide the Orgs drop-down.

  • hideApplicationSwitcher
    To show or hide the application switcher in V2 experience) and application selector icons in the V3 experience. In the V3 experience, it also hides the Admin settings menu in the user settings drop-down.

  • disableProfileAndHelp
    To show or hide the help and profile icons.
    In V2 experience, this parameter also controls the visibility of Help menu in the left navigation panel of the home page.
    In the V3 experience, the profile icon includes the Admin settings menu, which is also hidden when the profile icon is disabled via disableProfileAndHelp.

  • hideObjectSearch
    To show or hide the Object search bar in the top navigation in V2 and V3 experience modes.

  • hideNotification
    To show or hide the alert icon in the V3 experience.

  • hideHamburger
    To show or hide the hamburger icon in the V3 experience.

The following example hides the icons in top navigation and the application selection menu:

const embed = new AppEmbed("#embed", {
     //... other attributes
    showPrimaryNavbar: true,  // Show navigation bar
    hideApplicationSwitcher: true, // Hide application selector
    disableProfileAndHelp: true, // Hide Help and Profile icons in top navigation
    hideObjectSearch: true,  // Hide the object search bar in top navigation
});

Customize the left navigation panel on home pageπŸ”—

In the V2 and V3 experience modes, the left navigation panel on the Insights > Home page includes menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and more. You can hide this navigation panel by setting the hideHomepageLeftNav property to true in the SDK. Note that this attribute hides only the left navigation on the home page.

If you want to include the left navigation, but hide only a specific section in the Insights panel, use the hiddenHomeLeftNavItems property and specify the menu items to hide:

const embed = new AppEmbed("#embed", {
    //... V2 or V3 experience attributes
    //Show left navigation panel on the home page
    hideHomepageLeftNav: false,
    hiddenHomeLeftNavItems: [
        HomeLeftNavItem.MonitorSubscription,
        HomeLeftNavItem.SpotIQAnalysis
    ], // Hide SpotIQ analysis and Monitor subscriptions menu items
});

Customize home page experienceπŸ”—

The modular home in V2 and V3 experience include modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more.

To show or hide specific modules on the home page, use the hiddenHomepageModules parameter. To reorder the home page components, use the reorderedHomepageModules array.

The following example hides several home page components and specifies the order in which the remaining components appear on the home page:

const embed = new AppEmbed("#embed", {
    //...
    // Hide modules from the home page
    hiddenHomepageModules: [
        HomepageModule.Learning,
        HomepageModule.Trending
    ],
    // Custom order for visible modules
    reorderedHomepageModules: [
        HomepageModule.Search,
        HomepageModule.Favorite,
        HomepageModule.Watchlist,
        HomepageModule.MyLibrary
    ],
    //...other view configuration properties
});

Customize the search experience on home pageπŸ”—

You can set the search experience on the home page to function as an object search bar that allows finding popular objects, or as an AI search interface that allows natural language queries or Spotter sessions. You can also choose to hide it from the home page. To configure your preference, specify the following values in the homePageSearchBarMode attribute.

Search bar modeDescription

HomePageSearchBarMode.AI_ANSWER

Sets the natural language search bar that allows queries in natural language. If Spotter is enabled on your instance, you can use this setting to set the Spotter search bar on the home page.

HomePageSearchBarMode.OBJECT_SEARCH

Enables object search that allows users to find objects from the library.

HomePageSearchBarMode.NONE

Hides the search bar on the home page. Note that it only hides the Search bar on the Home page and doesn’t affect the Object Search bar visibility on the top navigation bar.

Note

If your instance is using the V1 classic experience and the homePageSearchBarMode parameter does not set the search context defined in your code, set isUnifiedSearchExperienceEnabled to false.

The following examples show the code snippets to set the home page search bar mode to Spotter or AI search in different experience modes:

V3 experience
import {
    AppEmbed,
    PrimaryNavbarVersion // Enum for V3 navigation experience
    HomePage, // Enum for home page experience settings
    HomePageSearchBarMode // Import the enum for search bar mode options
} from '@thoughtspot/visual-embed-sdk';

const embed = new AppEmbed("#embed", {
    discoveryExperience: {
        primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable v3 experience
        homePage: HomePage.Modular // modular home page experience
    },
    // Set the home page search bar to show the Spotter / AI search bar
    homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER
    // Other view configuration attributes
});
V2 experience
import {
    AppEmbed,
    HomePageSearchBarMode // Import the enum for search bar mode options
} from '@thoughtspot/visual-embed-sdk';

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true, // Enable v2 modular home page experience
    // Set the home page search bar to show the Spotter / AI search bar
    homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER
    // Other view configuration attributes
});
V1 classic experience
import {
    AppEmbed,
    HomePageSearchBarMode // Import the enum for search bar mode options
} from '@thoughtspot/visual-embed-sdk';

const embed = new AppEmbed("#embed", {
    // Set the home page search bar to show the Spotter / AI search bar
    homePageSearchBarMode: HomePageSearchBarMode.aiAnswer,
    // Disable the unified search experience
    isUnifiedSearchExperienceEnabled: false,
    //... other view configuration attributes
});

Customize list pagesπŸ”—

A list page in ThoughtSpot refers to a page that displays a list of objects, such as Answers, Liveboards, and Liveboard schedules. The list pages include columns for sorting, filtering, tagging, and performing bulk actions such as marking favorites, sharing, or deleting objects.

To customize the columns in list pages such as Liveboards and Answers, use the hiddenListColumns attribute. Valid values that correspond to the column names on the list pages are:

  • ListPageColumns.Author to show or hide the Author column

  • ListPageColumns.Favourite to show or hide the Favourite column

  • ListPageColumns.DateSort to show or hide the Last modified column

  • ListPageColumns.Tags to show or hide the Tags column

  • ListPageColumns.Share to show or hide the Share links in the column

The following example hides specific columns using the hiddenListColumns array:

import {
    AppEmbed, // Main class to embed the full ThoughtSpot app
    ListPageColumns // Enum for columns on list pages
} from '@thoughtspot/visual-embed-sdk';

const embed = new AppEmbed("#embed", {
    // hide Author, Share, and Tags columns on Answers and Liveboards listing pages
    hiddenListColumns: [
        ListPageColumns.Author,
        ListPageColumns.Share
    ],
    //... other view config attributes

});
Note

The hiddenListColumns: [ListPageColumns.Share] hides the Share column, but doesn’t remove the Share button above the list. To hide both the column and the Share (Action.Share) button above the list, use the hiddenActions or visibleActions array.

Customize the default page and navigation routesπŸ”—

In full application embedding, the home page is set as the default landing page when the embedded app loads.
To change the default settings, you can use either the pageId or path parameter in the Visual Embed SDK. If both path and pageId properties are specified, the path definition takes precedence.

Set the default page using pageIdπŸ”—

The pageId parameter in AppEmbed sets the default ThoughtSpot page to load using a value from the Page enumeration.

Valid values for this attribute are:

  • Page.Home for the ThoughtSpot Home page

  • Page.Search for the ThoughtSpot Search page

  • Page.Answers for the Answers page

  • Page.Liveboards for the Liveboards page

  • Page.Data for the Data page

  • Page.SpotIQ for the SpotIQ analyses page

ExampleπŸ”—

//Import Page enumeration
import { AppEmbed, Page } from '@thoughtspot/visual-embed-sdk';

const embed = new AppEmbed("#embed", {
    // Set the initial page
    pageId: Page.Liveboards,
    //... other view configuration attributes
});

Set the default page via pathπŸ”—

The path parameter allows setting the default ThoughtSpot application page using a URL path.

Valid strings for the path parameter are:

PageClassic experienceV2 and v3 experience

Home

path: "home"

path: "home"
path: "insights/home"

Insights

path: "home"

path: "home"
path: "insights/home"

Liveboards list page

path: "pinboards"

path: "pinboards"
path: "home/liveboards"
path: "insights/liveboards"

Liveboard page

path: "pinboard/<Liveboard-GUID>"

path: "pinboard/<Liveboard-GUID>"

Answers list page

path: "answers"

path: "answers"
path: "home/answers"
path: "insights/answers"

Saved Answer page

path: "saved-answer/<answer-GUID>"

path: "saved-answer/<Answer-GUID>"

Spotter

path: "conv-assist"

path: "conv-assist"
path: "insights/conv-assist"

Search data

path: "answer"

path: "answer"
path: "insights/answer"

Data

path: "data/tables/"

path: "data/tables/"

Model, tables, views

path: "data/tables/<object-GUID>"

path: "data/tables/<object-GUID>"

SpotIQ analysis list page

path: "insights"

path: "insights"
path: "insights/spotiq-analysis"

SpotIQ analysis page

path: "insight/<spotIQ-analysis-GUID>"

path: "insight/<spotIQ-analysis-GUID>"

Monitor

path: "monitor"

Supported settings include:

  • path: "monitor"

  • path: "home/monitor-alerts"

  • path: "insights/monitor-alerts"

ExampleπŸ”—

const embed = new AppEmbed("#embed", {
    // Set the initial page
    path: 'pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9',
    //... other view configuration attributes
});

Customize navigation between pages within the appπŸ”—

To programmatically control navigation between the pages within the embedded app, you can use the navigateToPage() method and custom actions.

Using navigateToPage()πŸ”—

The AppEmbed object includes a navigateToPage() method that can switch the currently loaded page in the embedded view.

The navigateToPage() method accepts the same string values used for the pageId or path attributes. When customizing the menu, use navigateToPage to create a route to the desired page.

// Navigate to the Answers page
embed.navigateToPage(Page.Answers);

// Navigate to the Answers page without reloading the iframe (noReload = true)
embed.navigateToPage(Page.Answers, true);

Using navigateToPage() with a custom actionπŸ”—

To add a custom action for in-app navigation, create a callback custom action and define the navigation path.

In this example, the view-report action on a Liveboard page calls the navigateTo method to open a specific Answer page when the user clicks the View report button.

// Listen for the CustomAction event triggered from the embedded ThoughtSpot app
appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => {
    // Check if the custom action ID is 'view-report'
    if (payload.payload.id === 'view-report') {
        // Navigate to the specific saved Answer page using its GUID
        appEmbed.navigateToPage(
            'saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e'
        );
    }
});

To navigate to a specific application page without initiating a reload, you can set the noReload attribute to true as shown in this example:

// Listen for the CustomAction event triggered from the embedded ThoughtSpot app
appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => {
    // Check if the custom action ID is 'view-report'
    if (payload.payload.id === 'view-report') {
        // Navigate to the specific saved Answer page using its GUID,
        // and set noReload to true to avoid reloading the iframe
        appEmbed.navigateToPage('saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e', true);
    }
});

Using history.back()πŸ”—

Page changes within the AppEmbed component register as part of the embedding app’s history to the web browser.

The standard JavaScript history.back() function will cause the AppEmbed component to go to the previously loaded page up until the very first ThoughtSpot page loaded within the component.

Detect changes in the currently loaded pageπŸ”—

Various actions the user takes within the embedded ThoughtSpot application may cause navigation within ThoughtSpot.

The embedding web application can listen for the EmbedEvent.RouteChange event by attaching an event listener to the AppEmbed object. The response has a currentPath property which is the path after the ThoughtSpot domain, for example:

pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9

To parse the currentPath into varying useful components, you can include this tsAppState object code in the global scope for use by any other web application code:

// Simple global object to handle details about what is visible in the AppEmbed component at a given moment
let tsAppState = {
  currentPath: startPath,
  currentDatasources: [], // Can be set later when detected from TML or other events
  // return what is being viewed at the moment, in the form that will translate to the pageId property if capitalized, or path property if not
  get pageType() {
      if (this.currentPath.includes('/saved-answer/')){
          return 'answer';
      }
      else if (this.currentPath.includes('/pinboard/')){
          return 'liveboard';
      }
      /*
      * Others are meant to match the exact pageId from SDK
      */
      else if(this.currentPath.includes('/answer/')){
          return 'Search';
      }
      else if(this.currentPath.includes('/answers')){
          return 'Answers';
      }
      else if (this.currentPath.includes('/pinboards')){
          return 'Liveboards';
      }
      else if(this.currentPath.includes('/insights')){
          return 'SpotIQ';
      }
      else if(this.currentPath.includes('/monitor')){
          return 'Monitor';
      }
      else if(this.currentPath.includes('/data')){
          return 'Data';
      }
      else {
          return 'Home';
      }
  },
  // If viewing an Answer or Liveboard, returns the GUID of that object from the parsed URL
  get objectId() {
      let pathParts = this.currentPath.split('/');
      // '/saved-answer/' is path for Answers (vs. /answer/)
      if (this.currentPath.includes('/saved-answer/')){
          answerGUID = pathParts[2];
          return pathParts[2];
      }
      // '/pinboard/' is path for saved Liveboards
      else if (this.currentPath.includes('/pinboard/')){
          let pathParts = this.currentPath.split('/');
          // May need adjustment for tabbed views to add in current Tab
          liveboardGUID = pathParts[2];
          return pathParts[2];
      }
      else{
          return null;
      }
  }

}

The following example shows the event listener code updating the global tsAppState object above whenever a change is detected within the embedded ThoughtSpot app:

embed.on(EmbedEvent.RouteChange, (response) => {
  // console.log("RouteChange fires");
  // console.log(response);
  // tsAppState object has currentPath property, which allows its other methods to parse out pageId, object type, GUIDs etc.
  tsAppState.currentPath = response.data.currentPath;
  console.log("TS App page is now: ", tsAppState.currentPath);

  // Update elements within your web application based on the new state of ThoughtSpot (adjust menu selections, etc.)

})

Customize Help menuπŸ”—

If you want to include the help menu and add custom links to it, ensure that the top navigation bar is visible and disableProfileAndHelp is set to false.

By default, the help menu in the embedded view shows the legacy information center controlled using Pendo. To enable the new information center and add custom links, set enablePendoHelp to false.

To add custom links to the help menu, use the customization settings available on the Admin settings > Help customization page. For more information, see ThoughtSpot Product Documentation.

const embed = new AppEmbed("#embed", {
    // Display the top navigation bar
    showPrimaryNavbar: true,
    // Show the profile and help icons in the navigation bar.
    disableProfileAndHelp: false,
    // Use the new ThoughtSpot information center for help and support.
    enablePendoHelp: false,
    // ... other view config attributes
});

Additional customization controlsπŸ”—

CSS customization allows overriding default styles in ThoughtSpot application pages.

If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as display: none;, visibility: hidden;, or height: 0px to hide it from the UI. To find the appropriate selector, use your browser’s Inspect tool to examine the style element in the Elements section of the browser’s Developer Tools.

.bk-data-scope .left-pane .header-lt {
  display: none !important;
  visibility: hidden !important;
}

An example of using direct selectors in a file is available in the complete.css sample on the ThoughtSpot GitHub repository.

You can also declare direct selectors using the rules property in the Visual Embed SDK configuration. This is useful for real-time testing, especially in the Visual Embed SDK playground. Note the required format for encoding CSS rules as JavaScript objects.

Β© 2025 ThoughtSpot Inc. All Rights Reserved.