Styling Existing Sisense Widgets with ComposeSDK's WidgetById
Summary: The article by Jeremy Friedel discusses styling options for Sisense widgets using ComposeSDK's WidgetById approach. It explains that WidgetById renders widgets directly by their dashboard and widget ID, offering various visual styling options via the styleOptions prop, but not underlying data modifications. The article highlights deprecated elements from previous SDK versions and introduces new features like config props for behavior controls. For comprehensive widget customization beyond mere styling, two alternative approaches are outlined: building native widgets from scratch, or using useGetWidgetModel to automate widget model retrieval from Fusion.
Styling Existing Sisense Widgets with ComposeSDK's WidgetById
When embedding an existing Sisense dashboard widget in a ComposeSDK application, there are three general approaches, each with a different tradeoff between speed and how much of the widget can be changed afterward. WidgetById renders the widget directly by its dashboard and widget ID, and stays connected to the live Fusion widget definition. Building a native widget from scratch, optionally using an existing widget as a visual reference, produces a fully independent ComposeSDK widget with every data option editable, at the cost of doing that work by hand. Between those two, useGetWidgetModel paired with widgetModelTranslator pulls an existing widget's definition from Fusion and converts it into props for a native widget component, automating what would otherwise be manual recreation.
This article covers the first approach, WidgetById, and specifically the large set of visual styling options it exposes through its styleOptions prop. The other two approaches are noted briefly near the end for context, not covered in depth here.
WidgetById was previously named DashboardWidget. That name was deprecated in ComposeSDK 1.23.0 and removed entirely in 2.0.0, along with the matching DashboardWidgetProps and DashboardWidgetStyleOptions types, which became WidgetByIdProps and WidgetByIdStyleOptions. Anyone maintaining code or working from an older tutorial that still references DashboardWidget is working against a removed component, not a currently deprecated one, and needs to migrate.
What WidgetById does and does not do
WidgetById takes a dashboardOid and a widgetOid, both required, and renders that widget as it exists on the connected Fusion instance. It supports a handful of props for scoping the widget further, additional filters and highlights, a filtersMergeStrategy for how those combine with the dashboard's own filters, and callbacks like onDataPointClick for interaction, but it does not expose the widget's underlying data options. Its dimensions, measures, and chart type stay whatever they are on the Fusion dashboard. That tradeoff is what makes it fast to use and what makes the other two approaches worth knowing about for cases that need more control.
Styling and visual configuration are handled through two separate props rather than one. styleOptions covers the visual styling this article focuses on, and a newer config prop covers widget behavior, such as which actions appear in the widget's header menu, described in its own section below.
Styling with styleOptions
The following example renders a widget and sets every field currently documented on WidgetByIdStyleOptions.
import { WidgetById } from '@sisense/sdk-ui';
export function ComposeSDKWidget() {
const styleOptions = {
backgroundColor: 'lightblue',
border: true,
borderColor: 'green',
cornerRadius: 'Large',
shadow: 'Dark',
spaceAround: 'Large',
header: {
hidden: false,
titleAlignment: 'Center',
backgroundColor: 'lightblue',
titleTextColor: 'blue',
},
height: 200,
width: 200,
};
return (
<WidgetById
widgetOid="65ab8958857ff900335db870"
dashboardOid="65ab8948857ff900335db86e"
styleOptions={styleOptions}
title="My Chart"
/>
);
}
Each field, its type, and what it controls:
backgroundColor(string, an HTML color) sets the background color of the widget itself.border(boolean) turns the widget container's border on or off.borderColor(string, an HTML color) sets that border's color, when enabled.cornerRadius("Large", "Medium", "Small", or "None") sets the corner radius of the widget container, similar to the CSS property of the same name.shadow("Dark", "Light", "Medium", or "None") sets the shadow level of the widget container. It only has a visible effect whenspaceAroundis also set to something other than "None".spaceAround("Large", "Medium", "Small", or "None") sets the space between the widget container's edge and the chart inside it.heightandwidth(number, in pixels) set the widget's fixed size. Left unset, the widget fills its container instead.header(object) groups the header and title styling below it.header.hidden(boolean) toggles the header and title's visibility entirely.header.titleAlignment("Left", "Center", or "Right") sets where the title sits in the header.header.backgroundColor(string, an HTML color) sets the header's background color.header.titleTextColor(string, an HTML color) sets the title's text color.header.dividerLine(boolean) toggles a divider line between the header and the chart.header.dividerLineColor(string, an HTML color) sets that divider line's color, when visible.
This is the same field set the older DashboardWidgetStyleOptions documented, with three additions since, a "None" option on cornerRadius, shadow, and spaceAround, and a "Right" option on header.titleAlignment. Nothing was removed from the older type.
Beyond styling, the config prop
WidgetById also accepts a config prop, of type WidgetConfig, which did not exist on the old DashboardWidget component. Where styleOptions controls appearance, config controls widget behavior, for a chart widget specifically that currently means:
actions.downloadCsv.enabledandactions.downloadExcel.enabledtoggle whether "Download as CSV" and "Download as Excel" appear in the widget's own header menu.header(a separate object from the one understyleOptions, this one typed asWidgetHeaderConfig) controls which items are available in that header menu.narrativeconfigures the widget's narrative text, where applicable.
Setting id on the widget is worth doing alongside config, since the Excel download action specifically depends on it to identify the widget being exported.
A note on a later change to WidgetById itself
ComposeSDK 2.3.0 refactored WidgetById to apply the dashboard's own palette to it by default, and changed its return type from a plain React element to one that can also resolve asynchronously. There may be other slight changes to visual appearance by default between the new and old component.
The other two approaches
For a widget that needs its data options changed, not just its appearance, WidgetById is not the right tool. Two other approaches exist.
Building the widget natively means constructing a ChartWidget, or the more general Widget facade component, directly, setting its chart type and data options in code, optionally using an existing Fusion widget as a visual reference while building it. The result has no ongoing connection to any Fusion widget or dashboard.
useGetWidgetModel automates part of that process. It is a React hook that retrieves an existing widget's model from a connected Fusion instance, given the same dashboardOid and widgetOid used above. Its result can be converted into props for a native widget component with a function from the widgetModelTranslator namespace, such as widgetModelTranslator.toWidgetProps, then rendered with <Widget {...widgetProps} />. This produces a fully native, editable widget without hand copying its data options, at the cost of needing that initial Fusion connection to retrieve them.
Useful links
