The dashboards:widget and dashboards:backgroundScript modules are generally available for new Jira dashboards and replace the legacy jira:dashboardGadget and jira:dashboardBackgroundScript modules.

If you don't already see the dual-create option on your Jira development or test site, you can enroll the site in the Developer Canary Program to enable creation of either a classic Jira dashboard or a new dashboard. For rollout, migration, and deprecation details, see the Jira Dashboards announcement.

Hook for accessing and updating widget configuration. You can call the hook anywhere in your code, as it subscribes to configuration updates. The configuration data loads asynchronously, so the output is undefined while loading.

For module configuration and setup instructions, see Dashboard widget.

Installation

Install Forge hooks using the @forge/hooks npm package. Import @forge/hooks using a bundler, such as Webpack.

Usage

To add the useWidgetConfig hook to your app:

1
2
import { useWidgetConfig } from "@forge/hooks/dashboards";

Here is an example of accessing and updating widget configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import React from "react";
import { useWidgetConfig } from "@forge/hooks/dashboards";

function MyWidget() {
  const { config, updateConfig } = useWidgetConfig();

  const handleUpdate = async () => {
    await updateConfig({
      title: "New Title",
    });
  };

  return (
    <div>
      <h1>{config?.title}</h1>
      <button onClick={handleUpdate}>Update Title</button>
    </div>
  );
}

Returns

config (Record<string, unknown> | undefined): Current widget configuration object. Returns undefined while loading or if no configuration is set.
updateConfig (function): Function to update configuration. Also triggers an update of the live editing view.