You can use the Embedding API to customize the look and feel of your embedded Tableau Pulse metrics by changing the font and colors used to render the metric in your web apps and web pages. The Embedding API provides a <theme-parameter>
for the <tableau-pulse>
web component that you can place in your HTML code.
For information about using Tableau Pulse and creating metric definitions, see Create Metrics with Tableau Pulse.
Note
To embed Tableau Pulse metrics in your web page or application, you must configure Tableau and your web application to use connected apps for authentication.For information about using connected apps, see Authentication and Embedded Views. and Use Tableau Connected Apps for Application Integration.
The following information will help get you started embedding metrics with Tableau Pulse.
In this section
<theme-parameter>
elements
<theme-parameter>
elementsThe Tableau Embedding API provides a <theme-parameter>
child element that you can apply to the <tableau-pulse>
component (or Pulse
object) to change the colors and fonts used.
There are two categories of theme parameters you can specify for the Pulse metric. The first category includes the page-level parameters, such as backgroundColor
and foregroundColor
and fonts that apply to the whole Pulse layout component. The second category includes the colors you can apply to the Pulse charts, such as axisGrid
and bar
. The page-level theme parameters have two attributes, the name of the property and its value. The chart parameters have a type attribute (type="chart"
) in addition to the name and value attributes of the property.
<theme-parameter>
to the Tableau Pulse web componentThe following example shows how you could specify a background color for the Pulse metric, by adding a <theme-parameter>
element to the Pulse web component.
<tableau-pulse id="tableauPulse"
src='<Your_Tableau_Pulse_URL>'
layout="default">
<theme-parameter name="backgroundColor" value="#fef"></theme-parameter>
</tableau-pulse>
For more information about changing background and foreground colors and chart properties, see Change colors for the Pulse metric and the list of page-level and chart properties you can customize.
<theme-parameter>
to Tableau Pulse using JavaScriptThe following example also shows how you can specify a background color, this time using JavaScript to add the <theme-parameter>
element to the Pulse web component.
// assumes a Pulse object has been created
const tableauPulse = document.querySelector("tableau-pulse");
// create a theme-parameter element
const theme1 = document.createElement("theme-parameter");
theme1.setAttribute("name", "backgroundColor");
theme1.setAttribute("value", "#fef");
tableauPulse.appendChild(theme1);
You can use the theme parameter to change the font used in the Pulse metric. You can select the font to use from Google Fonts. The Pulse metric supports a single font, but you can also specify the base font size (or smallest size) from a range of 12 to 18, inclusively. The base size is the smallest size font used for the range of text blocks and headings in the Pulse metric. The syntax for specifying the font and font size is as follows:
<theme-parameter name="fontCssUrl" value="URL"></theme-parameter>
<theme-parameter name="fontSize" value="SIZE"></theme-parameter>
The specify a font, provide a value for fontCssUrl
. The value is the URL is to the stylesheet for the Google Font you want to use.
To get the URL, go to Google Fonts.
Choose the font you want to use for the Pulse metric (for example, Bebas Neue).
Click the Get Font button.
Click the Get Embed Code button.
Copy the URL for the font from the embed code sample.
For example, the following embedded Pulse metric uses the Bebas Neue font, with a base size of 18 points.
<tableau-pulse id="tableauPulse"
src='https://online.tableau.com/pulse/site/mysite/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838'
layout="default">
<theme-parameter name="fontCssUrl" value="https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap"></theme-parameter>
<theme-parameter name="fontSize" value="18"></theme-parameter>
</tableau-pulse>
There are two categories of color parameters you can specify for the Pulse metric. The first category includes the page-level parameters, such as backgroundColor
and foregroundColor
that apply to the whole Pulse layout component. The second category includes the colors you can apply to the Pulse charts, such as axisGrid
and bar
.
You can use any valid CSS color, including predefined color names (red
, cyan
, chartreuse
, etc.), or RGB, HEX, HSL, RGBA, HSLA values. For example, the following values could be used for the color red:
"red"
"#f00"
"#ff0000"
"rgb(255, 0, 0)"
"hsl(0, 100%, 50%)"
The following settings set the page-level foreground color and the axis grid line for line and bar charts.
<theme-parameter name="foregroundColor" value="#808"></theme-parameter>
<theme-parameter type="chart" name="axisGrid" value="blue"></theme-parameter>
For more information about specifying colors, see CSS Colors.
Page parameter name | Accepted Values | Description |
---|---|---|
fontCssUrl |
URL | The URL to the Google Fonts stylesheet for the desired font. For example, "https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap" . |
fontSize |
integer | The base font size in pixels. The size must be between 12 and 18, inclusively. For example, <theme-parameter name="fontSize" value="16"></theme-parameter> |
backgroundColor |
CSS_Color | The background color of the entire layout. Accepts any valid CSS color. You can use predefined color names (red, cyan, chartreuse, etc.), or RGB, HEX, HSL, RGBA, HSLA values. For example, <theme-parameter name="backgroundColor" value="#cccccc"></theme-parameter> sets the background color as a light gray. |
backgroundColorOpaque |
CSS_Color | The opaque background color. Used on components that should not use the background color when the background is “transparent.” Accepts any valid CSS color other than “transparent.” |
foregroundColor |
CSS_Color | The color of text that exists on top of the background. Be sure to select a value that has sufficient contrast with the background color. |
Note: To set the background color (backgroundColor ) as transparent, specify the CSS color as "transparent" . Doing so enables backgroundColorOpaque to work as intended. That is, backgroundColorOpaque is used for components that should not use the background color when the background color is transparent. The value "rgba(0,0,0,0)" would still apply a transparent background color, but the logic that tells backgroundColorOpaque to apply only works when "transparent" is provided as the value for backgroundColor . |
The names for line and bar chart properties are organized into two categories (group names, and detailed names). To set the properties, you can specify the name of the parameter group (axis
, for example) or one of the detailed names in that group (axisGrid
, axisGridActive
, or barAxis
). The group name sets the default color for the detailed properties, unless those detailed properties are specified. Note that the order the properties appears makes a difference. If a detailed property is set, followed by the group property, the named group property is applied.
(Click on the image to open the image in a separate tab or window.)
(Click on the image to open the image in a separate tab or window.)
To set the properties, you can specify the name of the parameter group (axis
, for example) or one of the detailed names in that group (axisGrid
, axisGridActive
, or barAxis
). The group name sets the default color for the detailed properties, unless those detailed properties are specified. Note that the order the properties appear makes a difference. If a detailed property is set (axisGrid
), followed by the group property (axis
), the named group property overrides the detailed property.
Chart parameter group name | Chart Detailed names |
---|---|
axis |
axisGrid , axisGridActive , barAxis |
axisLabels |
axisLabel , barAxisLabel |
primary |
bar , currentValueDotBorder , line |
primaryLabel |
barLabel , currentValue |
average |
barAverage |
averageLabel |
barLabelAverage |
cumulative |
barCumulative |
cumulativeLabel |
barCumulativeLabel |
favorable |
barFavorable , changeFavorable |
favorableLabel |
barLabelFavorable |
unfavorable |
barUnfavorable , changeUnfavorable |
unfavorableLabel |
barLabelUnfavorable |
unSpecified |
barUnspecified |
unSpecifiedLabel |
barLabelUnspecified |
sum |
barSum |
For the bar and line chart properties, you need to specify the type (“chart
”) in addition to the name of the property.
<theme-parameter type="chart" name="axisGrid" value="#808"></theme-parameter>
The following example shows a Tableau Pulse web component that uses the <theme-parameter>
to customize the fonts, colors, and labels.
You can copy this code and modify it to suit your embedded application. You need to provide the URL for your Tableau Pulse metric.
<tableau-pulse id="tableauPulse"
src='<Your_Tableau_Pulse_URL>'
layout="default">
<theme-parameter name="fontCssUrl"
value="https://fonts.googleapis.com/css2?family=Faculty+Glyphic&display=swap"></theme-parameter>
<theme-parameter name="fontSize" value="18"></theme-parameter>
<theme-parameter name="backgroundColor" value="#fef"></theme-parameter>
<theme-parameter name="backgroundColorOpaque" value=""></theme-parameter>
<theme-parameter name="foregroundColor" value="#808"></theme-parameter>
<theme-parameter type="chart" name="axisGrid" value="#808"></theme-parameter>
<theme-parameter type="chart" name="axisGridActive" value="#808"></theme-parameter>
<theme-parameter type="chart" name="axisLabel" value="#808"></theme-parameter>
<theme-parameter type="chart" name="bar" value="#808"></theme-parameter>
<theme-parameter type="chart" name="barAverage" value="#606"></theme-parameter>
<theme-parameter type="chart" name="barAxis" value="#808"></theme-parameter>
<theme-parameter type="chart" name="barAxisLabel" value="#808"></theme-parameter>
<theme-parameter type="chart" name="barCumulative" value="#5B3C88"></theme-parameter>
<theme-parameter type="chart" name="barCumulativeLabel" value="#5B3C88"></theme-parameter>
<theme-parameter type="chart" name="barFavorable" value="#88BE88"></theme-parameter>
<theme-parameter type="chart" name="barLabel" value="#808"></theme-parameter>
<theme-parameter type="chart" name="barLabelAverage" value="#606"></theme-parameter>
<theme-parameter type="chart" name="barLabelFavorable" value="#339999"></theme-parameter>
<theme-parameter type="chart" name="barLabelUnfavorable" value="#999933"></theme-parameter>
<theme-parameter type="chart" name="barLabelUnspecified" value="#875787"></theme-parameter>
<theme-parameter type="chart" name="barSum" value="#875787"></theme-parameter>
<theme-parameter type="chart" name="barUnfavorable" value="#AF3C4B"></theme-parameter>
<theme-parameter type="chart" name="barUnspecified" value="#875787"></theme-parameter>
<theme-parameter type="chart" name="changeFavorable" value="#88BE88"></theme-parameter>
<theme-parameter type="chart" name="changeUnfavorable" value="#AF3C4B"></theme-parameter>
<theme-parameter type="chart" name="currentValue" value="#fff"></theme-parameter>
<theme-parameter type="chart" name="currentValueDot" value="#B200FF"></theme-parameter>
<theme-parameter type="chart" name="currentValueDotBorder" value="#808"></theme-parameter>
<theme-parameter type="chart" name="dotBorder" value="#808"></theme-parameter>
<theme-parameter type="chart" name="hoverDot" value="#B200FF"></theme-parameter>
<theme-parameter type="chart" name="hoverLine" value="#808"></theme-parameter>
<theme-parameter type="chart" name="line" value="#808"></theme-parameter>
<theme-parameter type="chart" name="projection" value="#468246"></theme-parameter>
<theme-parameter type="chart" name="range" value="#fef"></theme-parameter>
</tableau-pulse>
The following shows what the example Pulse theme would look like when embedded in a web page.