# Embed a Liveboard

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/embed-liveboard

# Embed a Liveboard

This page explains how to embed a ThoughtSpot Liveboard in your web page, portal, or application.

A ThoughtSpot Liveboard is an interactive dashboard that presents a collection of visualizations pinned by a user.

## Import the LiveboardEmbed package

Import the `LiveboardEmbed` SDK library to your application environment:

**npm**

```JavaScript
import {
    LiveboardEmbed,
    AuthType,
    init,
    prefetch,
    EmbedEvent
}
from '@thoughtspot/visual-embed-sdk';
```

**ES6**

```JavaScript
<script type = 'module'>
    import {
        LiveboardEmbed,
        AuthType,
        init,
        prefetch
    }
from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js';
```

## Initialize the SDK

[Initialize the SDK]({{navprefix}}/{{getting-started}}#initSdk) and define authentication attributes.

## Create an instance of the LiveboardEmbed class

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>',
});
```

For more information about the Liveboard embed object, classes, methods, interface properties, and enumeration members, see the following pages:

-   [LiveboardEmbed]({{navprefix}}/{{LiveboardEmbed}})
    
-   [LiveboardViewConfig]({{navprefix}}/{{LiveboardViewConfig}})
    
-   [Actions]({{navprefix}}/{{Action}})
    

## Customize Liveboard view

The `LiveboardEmbed` component includes the `[LiveboardViewConfig]({{navprefix}}/{{LiveboardViewConfig}})` object. This object provides various attributes and properties to [customize the look and feel of the Liveboard page]({{navprefix}}/{{css-customization}}), [control the visibility of menu actions]({{navprefix}}/{{embed-actions}}) and features, and [manage interactions between the host and embedded app]({{navprefix}}/{{embed-events}}).

The most common customization is controlling the visibility of menu items in the embedded view by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of [Action]({{navprefix}}/{{Action}}) IDs. For information about the other frequently used properties, see [common customization options]({{navprefix}}/{{embed-pinboard}}#common-customizations).

## Register, handle, and trigger events

Register event listeners.

```JavaScript
liveboardEmbed.on(EmbedEvent.init, showLoader)
liveboardEmbed.on(EmbedEvent.load, hideLoader)
```

For more information about events, see the following pages:

-   [HostEvent]({{navprefix}}/{{HostEvent}})
    
-   [EmbedEvent]({{navprefix}}/{{EmbedEvent}})
    
-   [Events and app integration]({{navprefix}}/{{embed-events}})
    

## Render the embedded Liveboard

Render the embedded Liveboard.

```JavaScript
liveboardEmbed.render();
```

## Verify the embedded object

1.  Load the embedded object in your app. If the embedding is successful, you see a Liveboard page with visualizations.
    
    ![Liveboard embed](/docs/doc-images/images/embed-lb.png)
    
2.  Explore the charts and tables, and verify that objects render and show the desired data.
    

## Common customization options

The **[LiveboardViewConfig]({{navprefix}}/{{LiveboardViewConfig}})** object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide the header, and more.

### Show/hide large UI elements

Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderSticky`, `showLiveboardTitle`, and `showLiveboardDescription` control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether `true` enables or disables the particular feature.

![LiveboardViewConfig parameters](/docs/doc-images/images/liveboard_view_config_callouts_2.png)

The `hideLiveboardHeader` property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only" use cases or for rebuilding your own menus and buttons using [HostEvents]({{navprefix}}/{{embed-events}}).

The following constructor disables the _sticky header_ and shows the Liveboard title, which is hidden by default:

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    isLiveboardHeaderSticky : false,
    showLiveboardTitle: true,
    liveboardId: '<%=liveboardGUID%>',
});
```

> **NOTE:** When fullHeight is set to true, the SDK ignores the isLiveboardHeaderSticky:true setting, and the Liveboard header is not sticky.

### Enable compact Liveboard header

By default, embedded Liveboards display a full-height header bar that contains the Liveboard title, description, filter chips, tab navigation, and action menu. You can switch to a more space-efficient layout by enabling the compact header.

The compact header reduces the vertical footprint of the header area, integrates tabs and filter chips into a single condensed row, and moves the **Edit** button into the header’s overflow action menu.

To enable the compact header, set `isLiveboardCompactHeaderEnabled` to `true` in the `LiveboardViewConfig` object. Note that the `isLiveboardCompactHeaderEnabled` attribute is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later.

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    //... other embed config properties
    isLiveboardCompactHeaderEnabled: true,
});
```

When `isLiveboardCompactHeaderEnabled` is `true`, the following UI changes apply compared to the standard header:

 
| Area | Change |
| --- | --- |
| 
Header height

 | 

The header renders in a condensed, shorter height to maximize the visible content area.

 |
| 

Edit button

 | 

The **Edit** button is removed from the top-level header and is accessible from the header overflow (**…​**) menu.

 |
| 

Filter chips

 | 

Filter chips are rendered inside the compact header’s integrated filter row, replacing the separate floating filter panel.

 |
| 

Tabs

 | 

The tab bar is incorporated into the compact header row, rather than appearing as a separate element below the header.

 |
| 

Sticky scroll behavior

 | 

The scroll threshold at which the sticky header attaches to the top of the viewport is recalculated for the compact header’s shorter height. This may affect the scroll position at which the header becomes sticky compared to the standard header.

 |
|  |  |

#### Hiding the Liveboard title in compact header

In the compact header, you can hide the Liveboard title by setting `showLiveboardTitle` to `false` in the `LiveboardViewConfig` object:

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    //... other embed config properties
    isLiveboardCompactHeaderEnabled: true,
    showLiveboardTitle: false,
});
```

### Set Liveboard tile gutter

The `liveboardGutter` property lets you control the spacing between Liveboard tiles and groups, and the grid’s outer layout padding, directly from your embed configuration. The value you set overrides the Liveboard’s saved styling setting.

Use this property when you need to enforce consistent tile spacing across embedded Liveboards, regardless of how individual Liveboards are styled in ThoughtSpot.

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>',
    liveboardGutter: 16,
});
liveboardEmbed.render();
```

The following rules apply to the `liveboardGutter` value:

-   Accepts non-negative integers (0 or greater).
    
-   A value of `0` removes all gutter space between tiles and the grid’s outer layout padding.
    
-   Negative numbers, decimal values, and non-numeric strings are ignored. The Liveboard falls back to its saved styling value.
    

> **NOTE:** liveboardGutter controls the spacing between tiles and groups, not the spacing within a group. The Liveboard header’s horizontal margin is controlled separately by the --ts-var-liveboard-header-horizontal-margin CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both liveboardGutter and --ts-var-liveboard-header-horizontal-margin to matching values. For more information, see Liveboard CSS variables.

### Customize Liveboard tabs

By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the `activeTabId` property in the Visual Embed SDK as shown in the example here:

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8",
    activeTabId: "05406350-44ce-488e-abc5-5e8cdd65cf3c",
});
```

> **NOTE:** The activeTabId property is available only in the LiveboardEmbed package and is not supported in the full application embed mode.

### Reduce visible tabs and visualizations

`visibleVizs` and `visibleTabs` allow you to limit the experience for certain users on a Liveboard with many more elements.

For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent [HostEvent]({{navprefix}}/{{embed-events}}) called `SetVisibleVizs` to make an update after the Liveboard has loaded).

### Customizing filter visibility

To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events.

```JavaScript
const embed = new LiveboardEmbed('#embed', {
  ... // other liveboard view config
  hideLiveboardHeader:true,
});
```

If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later.

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    //... other embed config properties
    isLiveboardCompactHeaderEnabled: true,
    hideIrrelevantChipsInLiveboardTabs: true,
});
```

When `hideIrrelevantChipsInLiveboardTabs` is `true`:

-   Filter chips backed by data sources that are **not used by any visualization on the active tab** are hidden automatically when the user switches tabs.
    
-   A **Show irrelevant filters** toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips.
    
-   When the user clicks **Show irrelevant filters**, a complementary **Hide irrelevant filters** button appears to restore the filtered view.
    

### Add Note tiles

You can add a [Liveboard Note tile](https://docs.thoughtspot.com/cloud/latest/liveboard-notes) with custom text, images, and links on an embedded Liveboard.

-   Only users with edit access to a Liveboard can add a Note tile.
    
-   Users require `Can upload data` privilege to upload an image to the note tile.
    
-   If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see [Security settings]({{navprefix}}/{{security-settings}}).
    

### Redefine Liveboard breakpoint widths

The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards.

These breakpoint widths are customizable for the embedded customers. Contact ThoughtSpot support for assistance with customization.

### 12-column layout in embedded Liveboards

By default, embedded Liveboards use a responsive layout that collapses from 12 columns to 2 columns at container widths of 1024px or less, and to a single column at 630px or less.

Use the `isLiveboardAlwaysOn12ColLayout` property in the SDK to prevent this collapse and keep the 12-column layout at all container widths.

To force the 12-column layout, set `isLiveboardAlwaysOn12ColLayout` to `true` in the `LiveboardViewConfig` object:

```JavaScript
const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<%=liveboardGUID%>',
    isLiveboardAlwaysOn12ColLayout: true,
});
```

The property is also supported on `AppEmbed` via `AppViewConfig`:

```JavaScript
const appEmbed = new AppEmbed(document.getElementById('ts-embed'), {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    isLiveboardAlwaysOn12ColLayout: true,
});
```

> **NOTE:** The CSS variables --ts-var-liveboard-dual-column-breakpoint and --ts-var-liveboard-single-column-breakpoint control the pixel thresholds at which the responsive layout collapses. Use isLiveboardAlwaysOn12ColLayout: true when you want to prevent layout collapse entirely, rather than adjust the breakpoint thresholds. For more information about the CSS layout variables available for Liveboard layout control, see Liveboard layout CSS variables.

### Liveboard browser cache and refresh

ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header.

> **NOTE:** Liveboard browser cache and refresh is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot support.

To enable Liveboard data caching, set `enableLiveboardDataCache` to `true`.

```javascript
const liveboardEmbed = new LiveboardEmbed('#embed-container', {
    frameParams: {
        width: '100%',
        height: '100%',
    },
    liveboardId: '<Your-Liveboard-ID>', //
    enableLiveboardDataCache: true, //
});
```

When data caching is enabled, the refresh icon appears in the Liveboard header. Users can click this button to clear the browser cache and fetch fresh data.

![Liveboard refresh](/docs/doc-images/images/liveboard-refresh.png)

The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow.

 
| ID | Description |
| --- | --- |
| 
[Action.RefreshLiveboardBrowserCache]({{navprefix}}/{{Action}}#_refreshliveboardbrowsercache)

 | 

Action ID to show, hide, or disable the **Refresh** button in the Liveboard header.

 |
| 

[EmbedEvent.RefreshLiveboardBrowserCache]({{navprefix}}/{{EmbedEvent}}#_refreshliveboardbrowsercache)

 | 

Emitted when a user clicks the **Refresh** button in the Liveboard header.

 |
| 

[HostEvent.RefreshLiveboardBrowserCache]({{navprefix}}/{{HostEvent}}#_refreshliveboardbrowsercache)

 | 

Triggers a browser cache refresh programmatically for all visualization containers on the embedded Liveboard.

 |

### Customize filters

To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the [runtime filters]({{navprefix}}/{{runtime-filters}}) feature in the Visual Embed SDK to apply filters at load time.

> **IMPORTANT:** Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK runtimeFilters property, the limit is configurable by a ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. For more information, see Runtime filter limit.

#### Updating filters

Use the following host events in the Visual Embed SDK to update filters:

-   [`HostEvent.UpdateFilters`](https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatefilters) to update Liveboard filters
    
-   [`HostEvent.UpdateRuntimeFilters`](https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateruntimefilters) to update runtime filters
    
-   [`HostEvent.UpdateCrossFilter`](https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatecrossfilter)
    

For more information and examples, see [Filter types and application layers]({{navprefix}}/{{filters_overview}}).

### Liveboard download options

Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view.

> **NOTE:** Starting with ThoughtSpot Cloud version 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the isContinuousLiveboardPDFEnabled and isLiveboardXLSXCSVDownloadEnabled parameters. The Download action in the Liveboard’s more options menu is controlled by Action.DownloadLiveboard instead of Action.Download and Action.DownloadAsPdf. Action.DownloadAsPdf remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard.

#### XLSX and CSV in Liveboard scheduled exports

To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` is set to `true`.

```javascript
const embed = new LiveboardEmbed('#tsEmbed', {
    //...
    isGranularXLSXCSVSchedulesEnabled: true, // enable scope selection for XLSX and CSV Liveboard scheduled jobs.
});
```

#### Download actions and behavior

  
| Download actions | SDK parameter | Action ID for show/hide control |
| --- | --- | --- |
| 
**Download** menu action

 | 

Enabled by default.

 | 

Use the `Action.DownloadLiveboard` to show, hide, or disable the Download action in the menu.





 |
| 

Continuous PDF

 | 

`isContinuousLiveboardPDFEnabled`  
Enables or disables the continuous PDF option in Liveboard downloads

 | 

Use the `Action.DownloadLiveboardAsContinuousPDF` action ID to show or hide the **PDF (Continuous)** option in the **Download** modal.





 |
| 

XLSX download

 | 

`isLiveboardXLSXCSVDownloadEnabled`  
Enables the XLSX and CSV download options in the Download modal.

 | 

`Action.DownloadLiveboardAsXlsx` - action ID to show or hide the XLSX option in the **Download** modal.





 |
| 

CSV download

 | 

`isLiveboardXLSXCSVDownloadEnabled`  
Enables the XLSX and CSV download options in the Download modal.





 | 

`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV option in the **Download** modal.





 |
| 

PDF cover and filter pages

 | 

None. UI options in PDF modal only.

 | 

Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog.





 |

#### Example

The following example enables the **PDF (Continuous)**, **XLSX**, and **CSV** options in the Liveboard **Download** modal.

```javascript
const embed = new LiveboardEmbed('#tsEmbed', {
  isContinuousLiveboardPDFEnabled: true,
  isLiveboardXLSXCSVDownloadEnabled: true,
});
```

To hide or disable the download options, specify the following action IDs:

```javascript
const embed = new LiveboardEmbed('#tsEmbed', {
  //...
  hiddenActions: [
    Action.DownloadLiveboard, // Hides the Download parent action from the more options menu
    Action.DownloadLiveboardAsContinuousPDF, // Hides the Continuous PDF download option from the Download modal
    Action.DownloadLiveboardAsCsv, // Hides the CSV download option from the Download modal
    Action.DownloadLiveboardAsXlsx // Hides the XLSX download option from the Download modal
  ],
  // Use either `hiddenActions` or visibleActions, not both, to avoid errors
  //visibleActions: [
    //Action.DownloadLiveboard, // Shows the Download parent action in the more options menu
    //Action.DownloadLiveboardAsContinuousPDF, // Shows the Continuous PDF download option
    //Action.DownloadLiveboardAsCsv, // Shows the CSV download option
    //Action.DownloadLiveboardAsXlsx // Shows the XLSX download option
  //]
});
```

```javascript
const embed = new LiveboardEmbed('#tsEmbed', {
  //...
  disabledActions: [
    Action.DownloadLiveboard,// Disables the Download parent action in the more options menu
    Action.DownloadLiveboardAsContinuousPDF, // Disables the Continuous PDF download option in the Download modal
    Action.DownloadLiveboardAsCsv, // Disables the CSV download option in the Download modal
    Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal
  ],
});
```

#### HostEvent workflow for the download actions

Use the HostEvent IDs to trigger download actions on an embedded Liveboard.

-   `HostEvent.DownloadLiveboardAsContinuousPDF`  
    To open the **Download** modal with the continuous PDF download option selected.
    
-   `HostEvent.DownloadAsPdf`  
    To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of the visualization in the `vizId` key.
    
-   `HostEvent.DownloadAsXlsx`  
    To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view.
    
-   `HostEvent.DownloadAsCsv`  
    To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view.
    

### Liveboard grouping and styling

You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. Note the following changes that occur in the Liveboard UI and layout when this feature is enabled.

-   All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables.
    
-   For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off.
    
-   If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error.
    
    ![Liveboard with groups styling error](/docs/doc-images/images/lb-grp-styling-error.png)
    
    To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly.
    

For more information, see [Liveboard grouping and styling](https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling).

For information about the CSS variables for this feature, see [CSS variables reference]({{navprefix}}/{{customize-css-styles}}#grp-style).

## Additional resources

-   For information about runtime overrides, see [Runtime filters]({{navprefix}}/{{runtime-filters}}) and [Runtime Parameter overrides]({{navprefix}}/{{runtime-parameters}}).
    
-   For code examples, see [Developer examples](https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/liveboard).
    
-   For more information about the SDK APIs and attributes, see [Visual Embed SDK Reference Guide]({{navprefix}}/{{VisualEmbedSdk}}).