Dashboard widget (EAP)

Dashboard widget module (EAP)

The dashboard widget module allows you to create interactive widgets that can be added to the dashboards in Atlassian Home. These widgets can:

• Display custom data and visualizations
• Provide user interaction capabilities
• Communicate with background scripts
• Be configured by users through edit modes

Example of a dashboard widget displaying custom content

Setup Instructions

You can create a dashboard widget app with the following steps:

1. Run forge create and follow the prompts, selecting the templates under Dashboards (EAP).
2. Run forge deploy to deploy the app.
3. Run forge install and follow the prompts to install the app to Jira context (even though it is only available in Atlassian Home).
4. Once the app is installed, navigate to your Atlassian site and go to the Dashboards section in Atlassian Home.
5. Click "Add widget" and find your widget in the Marketplace widget list.
6. Add your widget to the dashboard to see it in action.

Widget list

When users install your widget to their site, they'll see your widget in the widget list:

Widget selection interface showing available dashboard widgets on the right, and on the left showing the preview of the selected dashboard widget

Widget configuration

Users can configure your widget through the edit interface:

Widget configuration interface allowing users to customize widgets

Manifest configuration

modules.dashboards:widget

Custom UI example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
modules:
  dashboards:widget:
    - key: hello-world-widget
      title: Hello World Widget
      description: A sample dashboard widget
      thumbnail: https://example.com/icon.svg
      resource: widgetResource
      edit:
        resource: widgetEditResource

resources:
  - key: widgetResource
    path: static/widget/build
  - key: widgetEditResource
    path: static/widget-edit/build

UI Kit example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
modules:
  dashboards:widget:
    - key: hello-world-widget-ui-kit
      title: Hello World Widget (UI Kit)
      description: A sample dashboard widget using UI Kit
      thumbnail: https://example.com/icon.svg
      resource: widgetResource
      render: native
      resolver:
        function: widgetResolver
      edit:
        resource: widgetEditResource
        render: native
        resolver:
          function: widgetEditResolver

resources:
  - key: widgetResource
    path: static/widget/build
  - key: widgetEditResource
    path: static/widget-edit/build

functions:
  - key: widgetResolver
    handler: widgetResolver.handler
  - key: widgetEditResolver
    handler: widgetEditResolver.handler

Properties

edit object properties

aiContext object properties

data object properties

AI insights context

Dashboard widgets can contribute a structured, tabular view of their data to Atlassian Intelligence insights. The platform invokes the aiContext.data entry point declared on your module and passes the response to the AI as prompt context. This data powers both:

• Chart insights: AI-generated insights for an individual widget, shown in a dialog when you select the AI Insights menu button on the widget.
• Dashboard insights: AI-generated insights across all widgets on a dashboard, available from the floating Get insights button on the dashboard or through Rovo Chat.

Manifest configuration

Add an aiContext block to your dashboards:widget module and point its data field at a function (or a remote endpoint):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
modules:
  dashboards:widget:
    - key: hello-world-widget
      title: Hello World Widget
      description: A sample dashboard widget
      thumbnail: https://example.com/icon.svg
      resource: widgetResource
      edit:
        resource: widgetEditResource
      aiContext:
        data:
          function: aiContextResolver

resources:
  - key: widgetResource
    path: static/widget/build
  - key: widgetEditResource
    path: static/widget-edit/build

functions:
  - key: aiContextResolver
    handler: aiContext.handler

The referenced function must return an object matching the return-value schema. For a full handler example, see AI insights context data in the Examples section.

Return-value schema

Your response must be an object with the following fields:

A cell is a string, number, boolean, or null.

Import the response type from @forge/dashboards-bridge to type your function:

1
2
import type { ForgeAiContextResponse } from "@forge/dashboards-bridge";

ForgeAiContextResponse optionally accepts a union of column keys. For example, ForgeAiContextResponse<'issue_type' | 'count'> keeps your columns and object-row keys in agreement.

Limits

• Max rows: 1000.
• Max serialized size: 300,000 characters (the JSON.stringify of the whole payload). This keeps the prompt within the model's context window.

If you exceed either limit, the platform rejects the response and the widget's data isn't used for insights.

API Documentation

For detailed API documentation, see:

• Dashboard bridge APIs - APIs for widget configuration and lifecycle management
• useWidgetConfig - React hook for widget configuration
• useWidgetContext - React hook for widget context

Examples

Use the Dashboard bridge APIs and dashboard hooks for widget development.

Widget view

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import React, { useEffect, useState } from "react";
import { useWidgetConfig, useWidgetContext } from "@forge/hooks/dashboards";
import { widget } from "@forge/dashboards-bridge";

// Set preview configuration
widget.setPreviewConfig({
  title: "Sample Title",
});

export const DashboardWidget = () => {
  const { config } = useWidgetConfig();
  const { layout } = useWidgetContext();

  return (
    <div>
      <div>{config?.title || "Default Title"}</div>
      <div>
        Size: {layout?.width}x{layout?.height}
      </div>
    </div>
  );
};

export default DashboardWidget;

Widget configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import React from "react";
import { useWidgetConfig } from "@forge/hooks/dashboards";
import { widgetEdit } from "@forge/dashboards-bridge";

// Set up save handlers
widgetEdit.onSave(async (config, { widgetId }) => {
  console.log("Widget saved!", config, widgetId);
});

widgetEdit.onProductSave(async (config) => {
  console.log("Widget config before saving in-product!", config);
  return null; // return config to opt-in to in-product save
});

const WidgetEditMode = () => {
  const { config, updateConfig } = useWidgetConfig();

  return (
    <input
      type="text"
      placeholder="Widget Title"
      value={config?.title}
      onChange={(e) => {
        updateConfig({
          title: e.target.value,
        });
      }}
    />
  );
};

export default WidgetEditMode;

AI insights context data

The function referenced by aiContext.data returns a structured, tabular view of the widget's data for AI insights. The following example mixes both supported row styles: a positional array aligned to columns, and an object keyed by column key:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
export const handler = async () => {
  return {
    title: "Issues by type",
    type: "bar",
    description: "Breakdown of open issues by type",
    columns: [
      { key: "issue_type", label: "Issue Type" },
      { key: "count", label: "Count" },
    ],
    rows: [
      ["Bug", 25], // positional array, aligned to the columns order
      { issue_type: "Story", count: 40 }, // object keyed by column key
    ],
  };
};