global:ui UI Kit components (EAP)

The global UI Kit components provide the navigation experience for your app. They deliver a complete layout with a header, sidebar navigation, and main content area that integrates with the Atlassian platform.

You can only use the Global component inside the global:ui module.

These UI Kit components are exported from the @forge/react/global entry point.

Import

1
2
import {
  Global,
  Sidebar,
  LinkMenuItem,
  FlyOutMenuItem,
  ExpandableMenuItem,
  ReorderableMenuItems,
  HelpLink,
  PersonalSettings,
  PersonalSettingsItem,
  CreateButton,
  CreateMenuItem,
  Main,
} from "@forge/react/global";

Component hierarchy

The Global component is composed of sub-components that work together to create the full layout:

1
2
<Global>
├─ <HelpLink />
│
├─ <CreateButton />
│  └─ <CreateMenuItem />
│
├─ <PersonalSettings />
│  └─ <PersonalSettingsItem />
│
├─ <Sidebar />
│  ├─ <LinkMenuItem />
│  │
│  ├─ <ReorderableMenuItems />
│  │
│  ├─ <FlyOutMenuItem />
│  │  └─ <LinkMenuItem />
│  │
│  └─ <ExpandableMenuItem />
│     └─ <LinkMenuItem />
│
└─ <Main />
   └─ {Your app content}

Both <Sidebar> and <Main> must be present as direct children of <Global>.

Layout areas

The component renders three layout areas:

1. Header — Rendered automatically by the platform. Includes your app branding, the search component, Rovo Chat, profile, and settings. You do not configure the header in code; it uses properties from your manifest.
2. Sidebar — The left navigation panel. You configure the menu items using Sidebar, LinkMenuItem, ExpandableMenuItem, and related components.
3. Main content — The central area for your app's primary content, wrapped in <Main>.

Props

Global

The root component that wraps the full layout.

Sidebar

Renders the left navigation panel.

LinkMenuItem

A clickable navigation link in the sidebar.

ExpandableMenuItem

An expandable menu item that reveals nested links when selected.

FlyOutMenuItem

A sidebar item that opens a flyout containing nested menu items.

ReorderableMenuItems

Groups sidebar menu items that users can reorder. Use this when your app supports a customizable navigation order.

Main

Wraps your app's main content area.

HelpLink

Renders a help link in the app header. Use it to direct users to support, documentation, or other help resources for your app.

PersonalSettings

Renders a personal settings menu in the app header. Use it to group user-specific settings and account actions.

PersonalSettingsItem

Renders an item inside the personal settings menu.

CreateButton

Renders a create button in the app header. Use it to expose one or more create actions for your app.

CreateMenuItem

Renders an item inside the create menu.

Header

The header is rendered automatically. You do not configure it in code. It uses the following properties from your manifest:

The header automatically includes:

• App name and logo — From your manifest title and icon. Selecting it navigates to the root route (/).
• Search — Lets users search content indexed by the platform. Search indexes content from any Atlassian app your app is linked to.
• Settings — A dropdown for app admins to access the manage apps console.
• Rovo Chat — Opens the Rovo AI chat sidebar.
• Profile — Opens the user's profile and account settings.

For details on configuring title and icon, see the global:ui module reference.

Requirements and limitations

• <Sidebar> and <Main> must both be present as direct children of <Global>.

Usage example

The following example assembles a complete app layout with header actions, sidebar navigation, and main content:

1
2
import React, { useState } from "react";
import ForgeReconciler, { Button, Text } from "@forge/react";
import {
  Global,
  Sidebar,
  LinkMenuItem,
  ExpandableMenuItem,
  HelpLink,
  PersonalSettings,
  PersonalSettingsItem,
  ReorderableMenuItems,
  CreateButton,
  CreateMenuItem,
  FlyOutMenuItem,
  Main,
} from "@forge/react/global";

const initialNotes = [
  { id: "1", label: "Document 1", href: "/notes/1" },
  { id: "2", label: "Document 2", href: "/notes/2" },
  { id: "3", label: "Document 3", href: "/notes/3" },
];

const App = () => {
  const [notes, setNotes] = useState(initialNotes);
  const [message, setMessage] = useState(
    "Select an action from the header or sidebar."
  );

  const handleCreateDocument = () => {
    setMessage("Create document selected.");
  };

  const handleCreateFolder = () => {
    setMessage("Create folder selected.");
  };

  return (
    <Global>
      <HelpLink href="https://support.atlassian.com/" />

      <CreateButton>
        <CreateMenuItem
          label="Create document"
          onClick={handleCreateDocument}
        />
        <CreateMenuItem label="Create folder" onClick={handleCreateFolder} />
      </CreateButton>

      <PersonalSettings>
        <PersonalSettingsItem
          label="Notification preferences"
          onClick={() => {}}
        />
        <PersonalSettingsItem label="Preferences" onClick={() => {}} />
      </PersonalSettings>

      <Sidebar>
        <LinkMenuItem label="Home" href="/" />
        <LinkMenuItem label="Recent" href="/recent" />

        <ExpandableMenuItem label="Projects">
          <LinkMenuItem label="Project Alpha" href="/projects/alpha" />
          <LinkMenuItem label="Project Beta" href="/projects/beta" />
        </ExpandableMenuItem>

        <FlyOutMenuItem label="Resources">
          <LinkMenuItem label="Documentation" href="/resources/docs" />
          <LinkMenuItem label="Templates" href="/resources/templates" />
        </FlyOutMenuItem>

        <ReorderableMenuItems
          items={notes}
          onReorder={(items) => {
            setNotes(items);
            setMessage("Sidebar order changed.");
          }}
          onError={(error, currentItems, nextItems) => {
            console.error("Failed to persist sidebar order:", error);
          }}
        />
      </Sidebar>

      <Main>
        <Text>{message}</Text>
        <Button onClick={() => setMessage("Main content action selected.")}>
          Run action
        </Button>
      </Main>
    </Global>
  );
};

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