Dashboard plugins
Understand the dashboard plugin contract, lifecycle, bundling, runtime behavior, and maintenance requirements.
Dashboard plugins let you add custom code to the Dashboard component. Use a plugin to change how the dashboard renders content, add widgets, respond to dashboard events, or customize the dashboard layout and filters.
What a dashboard plugin is
A dashboard plugin is an object that implements a contract defined by GoodData.UI and is built and bundled for the GoodData.UI dashboard loader.
Register a plugin in a workspace to use it on one or more dashboards. You can parameterize each dashboard-to-plugin link so that the same plugin behaves differently on different dashboards.
Plugin contract and lifecycle
The plugin contract is an interface in @gooddata/sdk-ui-dashboard. See the
plugin contract source code.
The contract is versioned to allow for future breaking changes. The only supported version is currently v1.
The contract requires you to provide or implement:
- Properties that provide metadata about the plugin.
- The
registerfunction, called during dashboard initialization before the Dashboard component mounts. Register customizations and event handlers here. - The optional
onPluginLoadedfunction, called after the plugin assets load and before dashboard initialization. - The optional
onPluginUnloadfunction, called when the Dashboard component enhanced by the plugin unmounts.
Build and bundling
The dashboard loader uses webpack Module Federation to load and link plugins at runtime.
A plugin must be built into a bundle that is configured to inherit these dependencies from the context into which it is loaded:
- All
@gooddatadependencies reactandreact-dom
The plugin can depend on other packages and include custom assets as needed.
Build the plugin with the default webpack configuration from the GoodData.UI plugin template.
Runtime guarantees and implications
Lifecycle
The loader instantiates your plugin once for each dashboard load. When
implemented, onPluginLoaded, register, and onPluginUnload each run once
for that dashboard load.
Dependencies
The dashboard injects the latest GoodData.UI dependencies into the plugin at runtime. New dashboard features therefore become available without rebuilding the plugin, but a new dashboard feature can also be incompatible with an older deployed plugin even without an API-level breaking change. Follow the recommendations below to reduce that risk.
Exports and scheduled deliveries
A PDF, PPTX, or scheduled export of a dashboard is not rendered in the user’s browser. A GoodData service opens the dashboard in a headless browser in export mode, waits until the dashboard reports that every widget has rendered, and captures the result. That dashboard loads its linked plugins exactly as it does for a user, so your plugin runs on GoodData’s infrastructure as well as in browsers. The consequences:
- Everything your plugin changes is part of the export: custom widgets, replaced visualization renderers, layout changes, decorated or hidden filters. You can use this deliberately, for example to render a print-friendly variant of a widget or to decide how the dashboard splits into slides. See Customize dashboard export.
- The plugin files must be reachable from GoodData’s infrastructure, not only from your users’ network, with the same CORS and MIME type headers your users’ browsers need. A host that is only available inside your corporate network works in the browser and fails in the export.
- There is no user to interact with the export. State that a user creates by clicking in your widget is not there; render from the dashboard state and filters instead, and branch on export mode when the export should look different.
- A widget that loads data asynchronously must report it through
useDashboardAsyncRender, otherwise the export may capture it before the data arrives. See Prepare a custom widget for export.
Recommendations
- Use only the public dashboard plugin API and GoodData.UI interfaces. APIs marked alpha, beta, or internal can change without notice; see API maturity.
- Do not manipulate the CSS or DOM structure of the dashboard. Instead, stick to the theming guidelines.
- Create small, focused plugins. Avoid plugins that drastically change the dashboard’s behavior or appearance.
- For larger changes, consider using the standalone Dashboard component or building a custom dashboard.
Maintenance
Dashboard plugins integrate with a dashboard that keeps changing in GoodData Cloud and GoodData.CN, so breaking changes are sometimes necessary.
When this happens, you receive approximately six months to migrate your plugins. After that period, the dashboard runs only with the latest version, and plugins that have not been migrated will not load.
Capabilities
The customization APIs expose the dashboard extension points to your plugin.
The dashboard provides these APIs to register, where you can:
- Add/remove event handlers
- Register custom widget types and React components used to render them
- Place items that will render your custom widgets
- Override React components to use when rendering visualizations
Event handlers and React components can also use a subset of the dashboard selectors to read the current dashboard state.
Choose an extension point
Use the extension point that matches the part of the dashboard you need to change:
- Customize how saved visualizations render with
insightWidgets(). - Add arbitrary content such as images, forms, or additional text with
customWidgets(). - Change dashboard structure or export layout with
layout(). - Replace the filter bar or filter components with
filterBar()andfilters(). - Observe dashboard behavior or react to commands with the event handler API.
The visualization and custom-widget APIs serve different purposes. A custom
visualization renderer receives IDashboardInsightProps, including the
visualization and the widget that holds it; an arbitrary custom widget receives
IDashboardWidgetProps.
Current limitations
- GoodData does not host your built plugins. Host them yourself in a publicly available location that supports HTTPS.
Where to go next
- To build, host, and link your first plugin, follow Develop your first dashboard plugin. The plugin needs HTTPS hosting that sends CORS headers and serves
.mjsfiles astext/javascript, and the host must be allowed in your organization’s Content Security Policy; the tutorial covers both. - The
@gooddata/plugin-toolkitCLI bootstraps the project (npx @gooddata/plugin-toolkit@latest dashboard-plugin init) and adds, links, and unlinks plugins and their parameters. - For the customization and event APIs available in
register, see the Dashboard plugin API. - To run plugins in a dashboard rendered by your own React application rather than by GoodData, see Embed a dashboard with plugins.
Related
Scaffold a dashboard plugin, run it against a live dashboard, then build, host, register, and link it.
Implement the dashboard plugin lifecycle, customize visualizations, widgets, layouts, filters, and exports, and register dashboard event handlers.
Render a dashboard in your React application with its plugins, bundled with your app, linked in the workspace, or both.
Upgrade a dashboard plugin by rebuilding it from the latest toolkit template or updating its dependencies and configuration before testing and deployment.
Choose which layer of a dashboard widget to replace (the widget, the visualization, or its body) and how drills flow through custom renderers.