Bitbucket modules
Common modules
Compass modules
Confluence modules
Jira modules
Jira Service Management modules

Jira dashboard gadget

The jira:dashboardGadget module creates a dashboard gadget that is displayed on the Dashboards page.

This module can be used in Jira Work Management, Jira Software, and Jira Service Management. See the DashboardGadget component documentation for an example.


Dashboard Gadgets can be configured using their edit mode.


Dashboard Gadgets can be refreshed manually by your users and automatically. The automatic refresh interval (in minutes) is configured by submitting a refresh field as part of an edit view (the API accepts positive integers for this field).

UI Kit 1

When using the onSubmit method in the DashboardGadgetEdit component, provide a refresh field to the object returned by your onSubmit function.

const onSubmit = () => ({ ...otherFieldsToSubmit, refresh: 15 });

Custom UI and UI Kit

When using Custom UI and UI Kit to work with the Dashboard Gadget module, use the submit API as part of your edit view to provide a refresh field to the submit function:

await view.submit({ ...otherFieldsToSubmit, refresh: 15 });
Overriding default gadget refresh behavior
  1. Set the refreshable property to false in the gadget's manifest file.
  2. Write your own refresh logic by handling the JIRA_DASHBOARD_GADGET_REFRESH event using the events.on() function from the Forge bridge.
  3. Optionally, apply the refresh logic only when the origin and gadgetId properties of the payload satisfy a condition.
import { events } from '@forge/bridge';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const subscription = events.on('JIRA_DASHBOARD_GADGET_REFRESH', (payload) => {
      // the payload contains the following properties:
      // - payload.origin - either 'dashboard' or 'gadget' depending on which refresh button was clicked
      // - payload.gadgetId - the ID of the gadget initiating the refresh (only available if payload.origin === 'gadget')

      // you can obtain the ID of the currently rendered gadget using the view.getContext() function

    return () => {
      subscription.then(({ unsubscribe }) => unsubscribe());
  }, []);

  // render the gadget

When the user clicks the refresh button of any Forge dashboard gadget that has overridden the default refresh behavior, the JIRA_DASHBOARD_GADGET_REFRESH event will be triggered and all Forge gadgets will receive it. You can limit the scope of the refresh logic based on the available payload, for example with payload.origin === 'dashboard' || payload.gadgetId === thisGadgetId.

Conditional rendering

With Custom UI, you can define the same resource for viewing and editing your dashboard gadget.

First, define your manifest:

    - key: hello-world-gadget
      title: Hello world!
      description: A hello world dashboard gadget.
      resource: main # the resource used to view our dashboardGadget
        function: resolver
        resource: main # the same resource, used to edit our dashboardGadget configuration
  - key: main
    path: static/hello-world/build

Then in your Custom UI, use the view API to determine whether to display the view mode or edit mode:

// App.jsx
import React, { useEffect, useState } from 'react';
import { view } from '@forge/bridge';
import View from './View';
import Edit from './Edit';

function App() {
  const [context, setContext] = useState();

  useEffect(() => {
  }, []);

  if (!context) {
    return 'Loading...';

  return context.extension.entryPoint === 'edit' ? <Edit/> : <View/>;

export default App;




YesA key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringRequired if using UI Kit 1.A reference to the function module that defines the module. Only used in UI Kit 1.
resourcestringRequired if using custom UI or the latest version of UI Kit.A reference to the static resources entry that your context menu app wants to display. See resources for more details.
render'native'Yes for UI Kit.Indicates the module uses UI Kit.
resolver{ function: string } or
{ endpoint: string }

Set the function property if you are using a hosted function module for your resolver.

Set the endpoint property if you are using Forge remote to integrate with a remote back end.

titlestring or { text: string, href: string }YesCan be:
  • a plain string containing the gadget's title.
  • an object containing a text property containing the gadget's title and a href property containing a link that the user is sent to when they click the gadget’s title.
descriptionstringYesA description of what the gadget does.
thumbnailstringYesThe absolute URL of the icon that's displayed next to the gadget's name and description in the list of gadgets that can be added to a dashboard.
edit.functionstringA reference to the function module that provides the editing experience for dashboard gadgets.
edit.resourcestringA reference to the static resources entry that provides the editing experience for dashboard gadgets. See Resources for more details. To submit the view, use the submit API.
edit.render'native'Indicates if your editing experience should display as UI Kit.
refreshablebooleanSet the refreshable property of the dashboard item to false to override the native Jira refresh behavior.

Extension context

gadgetConfigurationobjectObject containing gadget configuration.
dashboard.idstringID of the dashboard.
gadget.idstringID of the gadget.
typestringThe type of the module.

Rate this page: