Last updated Mar 31, 2021

Warning

The components presented on this page belong to an older version of our UI Kit. While they are functional, they might not provide the optimal performance you seek for your application. We strongly recommend upgrading to the latest version of our UI Kit.

AdminPage

Renders a Jira page that is only accessible to Jira admins, selected from the Apps section of the left navigation of Jira admin settings.

Usage notes

AdminPage is the top-level component required for the jira:adminPage module.

Import statement

1
2
import ForgeUI, { AdminPage } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for the components to display on the page. Can contain any UI kit component.

Example

1
2
import ForgeUI, {AdminPage, render, Text} from '@forge/ui';

const App = () => {
    return (
        <AdminPage>
            <Text>Hello, world!</Text>
        </AdminPage>
    );
};
export const run = render(
    <App/>
);

CustomFieldContextConfig

The CustomFieldContextConfig component is returned from a function defined in the contextConfig property in the app manifest. When the component is returned, a view of the custom field type configuration details for a context are rendered.

This component can be used in Jira Work Management, Jira Software, and Jira Service Management to render a configured view of the field in a custom field context.

Usage

1
2
import ForgeUI, { CustomFieldContextConfig } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can contain any component except for Form, ConfigForm, MacroConfig, and all extension-specific components.
onSubmit(formData: FormData) => Promise<any> | anyYesAn event handler that can be asynchronous. The argument, formData, is an object of input field keys and their values (see the following example). The return value is either an object which can contain the field configuration and schema (only for custom field object type) or a promise that’s resolved with the returned object.

Object type

Object type custom fields can have the schema property in the return object of the onSubmit method. The schema property contains the JSON schema that is used to validate values stored in the field. Here is an example:

1
2
const onSubmit = (formData) => ({
  schema: {
    properties: {
        value: formData.value,
        currency: formData.currency
    }
  }
});

Example

This example shows how configuration details defining the maximum and minimum values for a slider component type can be retrieved, displayed, and saved. The example uses the useProductContext hook to extract the extensionContext that stores the configuration. Any modified configuration is then saved with the onSubmit method of the component.

1
2
import ForgeUI, {
  render,
  useProductContext,
  CustomFieldContextConfig,
  TextField,
} from "@forge/ui";

const ContextConfig = () => {
  const {extensionContext: {configuration = {}}} = useProductContext();
  
  const onSubmit = (formData) => ({
      configuration: {
          minValue: +formData.minValue || 0, 
          maxValue: +formData.maxValue || 100,
      }
  });

  return (
    <CustomFieldContextConfig onSubmit={onSubmit}>
      <TextField name="minValue" label="Minimum value" defaultValue={configuration.minValue}/>
      <TextField name="maxValue" label="Maximum value" defaultValue={configuration.maxValue}/>
    </CustomFieldContextConfig>
  );
};

export const runContextConfig = render(<ContextConfig />);

Preview

This screenshot shows the slider component's custom field context configuration page in edit mode.

CustomFieldEdit

A modal dialog used to edit a CustomField. The modal dialog opens when the CustomField is selected in Jira.

Usage notes

Import statement

1
2
import ForgeUI, { CustomField, CustomFieldView, CustomFieldEdit } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can contain any component except for Form, ConfigForm, MacroConfig, and all extension-specific components.
onSubmit(formData: FormData) => Promise<CustomFieldValue> | CustomFieldValueYesAn event handler that can be asynchronous. The argument, formData, is an object of input field keys and their values (see example below). The return value is either the field value or a promise that’s resolved with the returned field value. The value is checked against the validation expression defined in the manifest and must be the same type as custom field.
width"small" | "medium" | "large" | "x-large"The width of the edit dialog. This can range from the width of a small pop-up to a pop-up that’s almost full-screen. Defaults to medium.
headerstringThe title of the edit dialog. Defaults to Custom field edit.

onSubmit

The value returned from the onSubmit function must be of the same type as the custom field. For example, for a custom field of type string, the value returned from onSubmit should also be a string.

For custom fields storing collections of values, where for example you've set the type to be string and collection to be list, the value returned from onSubmit should be an array of strings. Otherwise, the custom field will not be saved at all.

Example

1
2
import ForgeUI, {
  render,
  CustomFieldEdit,
  Select,
  Option,
} from "@forge/ui";

const Edit = () => {
  const onSubmit = (values) => values.valueSelect;

  return (
    <CustomFieldEdit onSubmit={onSubmit} width="small" header="Example header">
      <Select label="Select Value " name="valueSelect">
        <Option label="low" value="low" />
        <Option label="medium" value="medium" />
        <Option label="high" value="high" />
      </Select>
    </CustomFieldEdit>
  );
};

export const runEdit = render(<Edit />);

CustomField

Renders content of a jira:customField module, which lets users add specific pieces of information to a Jira issue.

For more information, see Jira custom field and Jira custom field type.

A CustomField in view mode:

A CustomField in edit mode:

Usage notes

Import statement

1
2
import ForgeUI, { CustomField } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArrayYesThe view code for the custom field. Can only contain Code, Image, Text, Tooltip, Tag, TagGroup, User, and UserGroup components.

Example

1
2
import ForgeUI, {
  render,
  useProductContext,
  CustomField,
  Text,
  StatusLozenge,
} from "@forge/ui";

const App = () => {
  const {
    extensionContext: { fieldValue },
  } = useProductContext();

  const fieldAppearance = (value) => {
    switch (value) {
      case "medium":
        return "success";
      case "high":
        return "removed";
      default:
        return "default";
    }
  };

  return (
    <CustomField>
      <Text>
        <StatusLozenge
          text={fieldValue}
          appearance={fieldAppearance(fieldValue)}
        />
      </Text>
    </CustomField>
  );
};

export const run = render(<App />);

DashboardGadgetEdit

The DashboardGadgetEdit component is returned from a function defined in the edit property in the app manifest. When the component is returned, an edit mode is rendered for the dashboard gadget.

This component can be used in Jira Core, Jira Software, and Jira Service Desk to render an edit mode for a dashboard gadget in the Dashboards page.

In edit mode, dashboard gadgets use a mechanism built into Jira to update the stored gadget configuration.

Import statement

1
2
import ForgeUI, { DashboardGadgetEdit } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArrayYesThe edit code for the dashboard gadget. Can contain any UI Kit component.
onSubmit(formData: FormData) => PromiseYesAn event handler that can be asynchronous. The argument, formData, is an object made up of input field keys and their values (see the following example).

onSubmit

The onSubmit function must be provided for the gadget configuration to be saved. The values returned from onSubmit are the values that are saved as the gadget configuration.

Example

A simple example of a dashboard gadget edit component enabling the input of a name that is displayed in the app's view mode.

1
2
import ForgeUI, {
  render,
  DashboardGadgetEdit,
  TextField,
} from "@forge/ui";

const Edit = () => {
  const onSubmit = (values) => {
      return values;
  }

  return (
    <DashboardGadgetEdit onSubmit={onSubmit}>
      <TextField name="name" label="Say hello to:" />
    </DashboardGadgetEdit>
  );
};

export const runEdit = render(<Edit />);

Preview

This is the dashboard gadget edit mode created by the example code.

DashboardGadget

The DashboardGadget component is returned from a function defined in the app manifest to render content for a dashboard gadget.

This component can be used in Jira Core, Jira Software, and Jira Service Desk to render the gadget in the Dashboards page.

You can also use the DashboardGadgetEdit component to extend the gadget to save a configuration.

Import statement

1
2
import ForgeUI, { DashboardGadget } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArrayYesThe view code for the dashboard gadget. Can contain any UI Kit component.

Example

An example of a dashboard gadget component that displays a hello message. The user can input a name in the edit mode of this app that is used in the message; otherwise, the message says "Hello world."

1
2
import ForgeUI, {
  render,
  DashboardGadget,
  Text,
  useProductContext,
} from "@forge/ui";

const App = () => {
  const {
    extensionContext: { gadgetConfiguration },
  } = useProductContext();

  return (
    <DashboardGadget>
      <Text
        content={`Hello ${gadgetConfiguration.name || "world"}`}
      />
    </DashboardGadget>
  );
};

export const run = render(<App />);

Preview

This is the dashboard gadget view created by the example code.

See DashboardGadgetEdit for an example of an editable gadget.

GlobalPage

Renders a Jira page selected from the Apps section of the main navigation.

Usage notes

GlobalPage is the top-level component required for the jira:globalPage module.

Import statement

1
2
import ForgeUI, { GlobalPage } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for the components to display on the page. Can contain any UI kit component.

Example

1
2
import ForgeUI, { GlobalPage, render, Text } from '@forge/ui';

const App = () => {
    return (
        <GlobalPage>
            <Text>Hello, world!</Text>
        </GlobalPage>
    );
};
export const run = render(<App/>);

IssueAction

A modal dialog triggered from the more actions (...) menu in Jira.

This is an example of an IssueAction button:

This is an example of the triggered modal dialog:

Usage notes

IssueAction is the top-level component required for the jira:issueAction module.

Import statement

1
2
import ForgeUI, { IssueAction } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can only contain ModalDialog.

Example

1
2
import ForgeUI, {render, Text, IssueAction, ModalDialog, useState} from '@forge/ui';

const App = () => {
    const [isOpen, setOpen] = useState(true)

    if (!isOpen) {
        return null;
    }

    return (
        <ModalDialog header="Hello" onClose={() => setOpen(false)}>
            <Text>Hello world</Text>
        </ModalDialog>
    );
};

export const run = render(
    <IssueAction>
        <App/>
    </IssueAction>
);

IssueActivity

A piece of content displayed in the Activity panel of a Jira issue.

Usage notes

Import statement

1
2
import ForgeUI, { IssueActivity } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can contain any UI kit component.

Example

1
2
import ForgeUI, { render, IssueActivity, Text } from "@forge/ui";

const App = () => {
  return <Text>Hello from the Issue activity!</Text>;
};

export const run = render(
  <IssueActivity>
    <App />
  </IssueActivity>
);

IssueContext

A selectable field in the right panel of a Jira issue, which shows/hides content.

Usage notes

Import statement

1
2
import ForgeUI, { IssueContext } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can contain any UI kit component.

Example

1
2
import ForgeUI, { render, IssueContext, Text } from "@forge/ui";

const App = () => {
  return <Text>Hello from the Issue context panel!</Text>;
};

export const run = render(
  <IssueContext>
    <App />
  </IssueContext>
);

IssueGlance

A selectable field in the right panel of a Jira issue, which shows/hides content.

Usage notes

Import statement

1
2
import ForgeUI, { IssueGlance } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can contain any UI kit component.

Example

1
2
import ForgeUI, { render, IssueGlance, Text } from "@forge/ui";

const App = () => {
  return <Text>Hello from the Issue glance!</Text>;
};

export const run = render(
  <IssueGlance>
    <App />
  </IssueGlance>
);

IssuePanelAction

An item in the more actions (•••) menu of an IssuePanel.

Usage notes

  • It must be provided as an argument to the actions property of the IssuePanel component.
  • You can view existing issue panel actions via the more actions (•••) menu.

Import statement

1
2
import ForgeUI, { IssuePanelAction } from '@forge/ui';

Props

NameTypeRequiredDescription
textstringYesThe name of the item that’s added to the actions menu of an issue panel.
onClick() => void|Promise<void>YesAn event handler executed when the item is clicked. You can perform state updates inside this function.

Example

1
2
import ForgeUI, {IssuePanel, IssuePanelAction, render, Text, useProductContext, useState} from '@forge/ui';

const App = () => {
    const [waveCount, setWaveCount] = useState(0);
    return (
        <IssuePanel actions={[
            <IssuePanelAction text="Custom action" onClick={() => {
                setWaveCount(waveCount + 1);
            }}/>
        ]}>
            <Text>Hello, world! {"👋".repeat(waveCount)}</Text>
        </IssuePanel>
    );
};
export const run = render(
    <App/>
);

IssuePanel

A piece of content displayed in the body of a Jira issue.

Usage notes

The following context variables are available for issue panels:

  • localId - The unique ID of the panel, which makes panel instances distinct from each other if allowMultiple is set to true.
  • extensionContext.isNewToIssue - This variable is set to true when a panel has just been added to an issue; otherwise, it's false.

The example shows how to access these variables with the useProductContext UI hook.

Import statement

1
2
import ForgeUI, { IssuePanel } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for displaying multiple components. Can contain any UI kit component.
actionsArray<IssuePanelAction>A list of IssuePanelAction components that correspond to items in the actions menu. No more than five actions can be defined.

Example

1
2
import ForgeUI, {IssuePanel, IssuePanelAction, render, Text, useProductContext, useState} from '@forge/ui';

const App = () => {
    const {localId: panelId, extensionContext: {isNewToIssue}} = useProductContext();
    return (
        <IssuePanel actions={[
            <IssuePanelAction text="Custom action" onClick={() => {}}/>
        ]}>
            <Text>Hello, world!</Text>
        </IssuePanel>
    );
};
export const run = render(
    <App/>
);

ProjectPage

Renders content of the jira:projectPage module on a Jira page.

Usage notes

ProjectPage is the top-level component required for the jira:projectPage module.

Import statement

1
2
import ForgeUI, { ProjectPage } from "@forge/ui";

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for the components to display on the page. Can contain any UI kit component.

Example

1
2
import ForgeUI, { ProjectPage, render, Text } from "@forge/ui";

const App = () => {
  return (
    <ProjectPage>
      <Text>Hello, world!</Text>
    </ProjectPage>
  );
};
export const run = render(<App />);

ProjectSettingsPage

Renders a Jira page selected from the project settings sidebar.

Usage notes

ProjectSettingsPage is the top-level component required for the jira:projectSettingsPage module.

Import statement

1
2
import ForgeUI, { ProjectSettingsPage } from '@forge/ui';

Props

NameTypeRequiredDescription
childrenArray<ForgeComponent>YesA container for the components to display on the page. Can contain any UI kit component.

Example

1
2
import ForgeUI, { ProjectSettingsPage, render, Text } from '@forge/ui';

const App = () => {
    return (
        <ProjectSettingsPage>
            <Text>Hello, world!</Text>
        </ProjectSettingsPage>
    );
};
export const run = render(
    <App/>
);

Rate this page: