UI Kit components
UI Kit hooks
Forge bridge APIs
Jira bridge APIs
Upgrade UI Kit versions
Previous versions

Forge’s EAP offers experimental features to selected users for testing and feedback purposes. These features are unsupported and not recommended for use in production environments. They are also subject to change without notice.

For more details , see Forge EAP, Preview, and GA.

Frame (EAP)

We have introduced the Frame component to offer a structured approach for integrating custom UI resources, ensuring they are integrated seamlessly within the UI Kit.

Description

A Frame is a container that renders a static frontend app. This provides you with full flexibility to implement your desired user interface using static resources, such as HTML, CSS, JavaScript, images, and videos.

Props

NameTypeRequiredDescription
resourcestringYesThis is the key of the resource to be loaded in the Frame. The resource must be defined in the app’s manifest.yml file. See Resources for how to define a resource. Unlike the default resource for a UI Kit module, Frame resources must point to a build folder.

Example

Manifest.yml declaration

Add the built output path directory of the Frame component resources in the manifest.yml file:

1
2
resources:
  - key: my-frame-component
    path: resources/my-frame-component/build

Frontend index.jsx file

Utilize the Frame component in the UI Kit app by employing the Frame tag with the resource property that links to the resource key (my-frame-component) of the designated frame component specified in the manifest.yml file.

We recommend placing your web frontend resource in <project_root>/resources/<my_frame_resource> to keep it separate from UI Kit resources. The content of the web frontend resource can consist of a static frontend based on any web frameworks as long as the final build assets contain index.html as the entry point.

1
2

import React from 'react';
import ForgeReconciler, { Text, Frame } from '@forge/react';

const App = () => {
  return (
    <>
      <Text>[UI Kit] Hello world!</Text>
      <Frame resource="my-frame-component" />
    </>
  );
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Get started with a clean project

We have created a repository for a project that features a clean-slate Forge app, developed in JavaScript, for the Confluence global page module. It is provided as a starting point for Forge app development, utilizing the UI Kit Frame component.

Go to the repo to clone or fork the project.

Tutorial

In this tutorial, we will showcase a logo designer app that renders a preview of the designed icon within the Frame component: Go to the tutorial.

Known limitations and issues

Issues

  • The Forge bridge invoke does not work within the Frame component in certain Jira modules:

    • jira:issueAction
    • jira:projectPage
    • jira:issueActivity
    • jira:issueContext, and few others.

    The support for these extension points is currently in progress, and is expected to be available after EAP. In the meantime, one of the possible workarounds is to initiate the invoke calls from the UI Kit part of the application.

  • The createHistory API is not functional within the Frame component for Jira modules. The work to support this feature is currently in progress, and is expected to be available after EAP. In the meantime, one of the possible workarounds is to utilise the createHistory API from the UI Kit part of the application.

  • The Custom UI ViewIssueModal does not work within the Frame component for Jira modules. The support for these extension points is currently in progress, and is expected to be available after EAP.

Limitations

  • Only a single Frame component can be rendered per module to minimize potential performance impact.
  • If the Frame component does not resize correctly within the application upon layout updates, we recommend checking and confirming that the sizing properties of the root container are defined using non-viewport-related units such as %, px, em, and so on. This limitation is because the Frame component's root container does not well support viewport-based relative sizing units like vh and vw.

Supported modules

For the EAP release, support for the Frame component has been enabled in the following modules:

Other modules of the Confluence, Jira, JSM, and Bitbucket products are supported, but since they're part of the Early Access Program (EAP), we haven't fully tested their modules yet, so we can't guarantee complete support at this moment.

ProductModule
Confluence Macro
Global Page
Jira Issue Panel
Global Page
Custom Field. Frame component can only be used within the Custom Field Edit part.
Admin Page
Compass Not Supported

Rate this page: