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.
Renders a Jira page that is only accessible to Jira admins, selected
from the Apps
section of the left navigation of Jira admin settings.
AdminPage
is the top-level component required for the jira:adminPage
module.
1 2import ForgeUI, { AdminPage } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for the components to display on the page. Can contain any UI kit component. |
1 2import ForgeUI, {AdminPage, render, Text} from '@forge/ui'; const App = () => { return ( <AdminPage> <Text>Hello, world!</Text> </AdminPage> ); }; export const run = render( <App/> );
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.
1 2import ForgeUI, { CustomFieldContextConfig } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can contain any component except for Form , ConfigForm , MacroConfig , and all extension-specific components. |
onSubmit | (formData: FormData) => Promise<any> | any | Yes | An 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 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 2const onSubmit = (formData) => ({ schema: { properties: { value: formData.value, currency: formData.currency } } });
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 2import 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 />);
This screenshot shows the slider component's custom field context configuration page in edit mode.
A modal dialog used to edit a CustomField.
The modal dialog opens when the CustomField
is selected in Jira.
edit
property of the
jira:customField
module.1 2import ForgeUI, { CustomField, CustomFieldView, CustomFieldEdit } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can contain any component except for Form , ConfigForm , MacroConfig , and all extension-specific components. |
onSubmit | (formData: FormData) => Promise<CustomFieldValue> | CustomFieldValue | Yes | An 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 . | |
header | string | The title of the edit dialog. Defaults to Custom field edit . |
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.
1 2import 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 />);
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:
function
defined in the app manifest.1 2import ForgeUI, { CustomField } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array | Yes | The view code for the custom field. Can only contain Code , Image , Text , Tooltip , Tag , TagGroup , User , and UserGroup components. |
1 2import 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 />);
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.
1 2import ForgeUI, { DashboardGadgetEdit } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array | Yes | The edit code for the dashboard gadget. Can contain any UI Kit component. |
onSubmit | (formData: FormData) => Promise | Yes | An 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).
|
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.
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 2import 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 />);
This is the dashboard gadget edit mode created by the example code.
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.
1 2import ForgeUI, { DashboardGadget } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array | Yes | The view code for the dashboard gadget. Can contain any UI Kit component. |
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 2import 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 />);
This is the dashboard gadget view created by the example code.
See DashboardGadgetEdit for an example of an editable gadget.
Renders a Jira page selected from the Apps
section of the main navigation.
GlobalPage
is the top-level component required for the jira:globalPage
module.
1 2import ForgeUI, { GlobalPage } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for the components to display on the page. Can contain any UI kit component. |
1 2import ForgeUI, { GlobalPage, render, Text } from '@forge/ui'; const App = () => { return ( <GlobalPage> <Text>Hello, world!</Text> </GlobalPage> ); }; export const run = render(<App/>);
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:
IssueAction
is the top-level component required for the
jira:issueAction
module.
1 2import ForgeUI, { IssueAction } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can only contain ModalDialog. |
1 2import 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> );
A piece of content displayed in the Activity panel of a Jira issue.
IssueActivity
is the top-level component required for the
jira:issueActivity
module.1 2import ForgeUI, { IssueActivity } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can contain any UI kit component. |
1 2import ForgeUI, { render, IssueActivity, Text } from "@forge/ui"; const App = () => { return <Text>Hello from the Issue activity!</Text>; }; export const run = render( <IssueActivity> <App /> </IssueActivity> );
A selectable field in the right panel of a Jira issue, which shows/hides content.
IssueContext
is the top-level component required for the jira:issueContext
module.
Can be used in Jira Work Management, Jira Software, and Jira Service Management new issue view.
1 2import ForgeUI, { IssueContext } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can contain any UI kit component. |
1 2import 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> );
A selectable field in the right panel of a Jira issue, which shows/hides content.
IssueGlance
is the top-level component required for the jira:issueGlance
module.
Can be used in Jira Work Management, Jira Software, and Jira Service Management new issue view.
1 2import ForgeUI, { IssueGlance } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can contain any UI kit component. |
1 2import ForgeUI, { render, IssueGlance, Text } from "@forge/ui"; const App = () => { return <Text>Hello from the Issue glance!</Text>; }; export const run = render( <IssueGlance> <App /> </IssueGlance> );
An item in the more actions (•••) menu of an IssuePanel.
actions
property of the
IssuePanel component.1 2import ForgeUI, { IssuePanelAction } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
text | string | Yes | The name of the item that’s added to the actions menu of an issue panel. |
onClick | () => void|Promise<void> | Yes | An event handler executed when the item is clicked. You can perform state updates inside this function. |
1 2import 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/> );
A piece of content displayed in the body of a Jira issue.
IssuePanel
is the top-level component required for the jira:issuePanel
module.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.
1 2import ForgeUI, { IssuePanel } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for displaying multiple components. Can contain any UI kit component. |
actions | Array<IssuePanelAction> | A list of IssuePanelAction components that correspond to items in the actions menu. No more than five actions can be defined. |
1 2import 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/> );
Renders content of the jira:projectPage
module on a Jira page.
ProjectPage
is the top-level component required for the
jira:projectPage
module.
1 2import ForgeUI, { ProjectPage } from "@forge/ui";
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for the components to display on the page. Can contain any UI kit component. |
1 2import ForgeUI, { ProjectPage, render, Text } from "@forge/ui"; const App = () => { return ( <ProjectPage> <Text>Hello, world!</Text> </ProjectPage> ); }; export const run = render(<App />);
Renders a Jira page selected from the project settings sidebar.
ProjectSettingsPage
is the top-level component required for the jira:projectSettingsPage
module.
1 2import ForgeUI, { ProjectSettingsPage } from '@forge/ui';
Name | Type | Required | Description |
---|---|---|---|
children | Array<ForgeComponent> | Yes | A container for the components to display on the page. Can contain any UI kit component. |
1 2import ForgeUI, { ProjectSettingsPage, render, Text } from '@forge/ui'; const App = () => { return ( <ProjectSettingsPage> <Text>Hello, world!</Text> </ProjectSettingsPage> ); }; export const run = render( <App/> );
Rate this page: