Custom Component Widget

Embed custom HTML or React code for bespoke visualizations. Last-resort option when standard widgets can't achieve the desired result.

Render Modes

• HTML — Sandboxed iframe. Pre-loadable libraries: D3.js, Chart.js, Tailwind CSS. Data arrives via widgetdata event.
• React — Inline with dashboard theme. Code receives ctx object with React hooks, data, and formatting utilities.

Data Connection

• Static — No data connection, pure visual content
• Custom SQL — Write SQL with placeholders
• Table + Metrics — Standard data selection

Pre-built example templates are available from the properties panel.

Get started

1. Add a custom component widget

1. 1In Edit Mode, click the + Custom button in the floating toolbar at the bottom of the page.
2. 2The widget appears on the dashboard with the Properties Panel open on the right.
3. 3In the Properties Panel, verify the Render Mode dropdown shows HTML (sandboxed iframe) by default, and a Code text area is visible below it.
4. 4Close the Properties Panel.

Result: The widget displays the placeholder text "Edit this widget to add your custom component" until code is entered.

2. Write HTML content

1. 1Open the Properties Panel for the custom component widget.
2. 2Confirm Render Mode is set to HTML (sandboxed iframe) (the default).
3. 3Click the Code text area, select all existing text, and type your HTML markup.
4. 4Close the Properties Panel.

Result: The widget renders your HTML inside a sandboxed iframe. Content updates each time you edit the code.

Use React mode

3. Switch to React mode and write a component

1. 1Open the Properties Panel and click the Render Mode dropdown.
2. 2Select React (inline, themed).
3. 3Click the Code text area, select all text, and write your component using ctx.createElement syntax (not JSX).

Result: The widget renders inline without an iframe, using the dashboard's theme. You have access to ctx.data, ctx.columns, and other context variables.

4. Switch between HTML and React modes

1. 1Open the Render Mode dropdown and switch between HTML (sandboxed iframe) and React (inline, themed).
2. 2Each mode automatically loads its own starter template in the Code editor when you switch.

Note: Switching modes replaces the code with a mode-specific template — your previous code is not preserved. HTML mode renders in an iframe; React mode renders inline.

5. Handle React compilation errors

1. 1In React mode, if your code contains a syntax error, the widget displays a Compilation Error message with a warning icon and error details.
2. 2Other widgets on the dashboard are not affected.
3. 3Fix the code in the Code editor and the widget automatically re-renders without a page refresh.

Result: Errors are contained to the widget and shown inline. The page does not crash.

6. Enable chromeless mode

1. 1Open the Properties Panel and scroll down to the Layout section.
2. 2Enable the Chromeless (fullscreen) toggle.
3. 3Close the Properties Panel.

Result: The widget renders without a card border, background, or title — content fills the entire widget area. This is useful for custom visualizations that manage their own styling.