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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import {
  Global,
  Sidebar,
  LinkMenuItem,
  FlyOutMenuItem,
  ExpandableMenuItem,
  MenuSection,
  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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<Global>
├─ <HelpLink />
│
├─ <CreateButton />
│  └─ <CreateMenuItem />
│
├─ <PersonalSettings />
│  └─ <PersonalSettingsItem />
│
├─ <Sidebar />
│  ├─ <MenuSection />
│  │  ├─ <LinkMenuItem />
│  │  ├─ <ReorderableMenuItems />
│  │  ├─ <FlyOutMenuItem />
│  │  └─ <ExpandableMenuItem />
│  │
│  ├─ <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. When the forYouMenuItem prop is true, the For you menu item is displayed at the top of the sidebar and the app uses the route /for-you as its home page. When the forYouMenuItem prop is false, the For you menu item is hidden and the app uses the root route (/) as its home page. Below it, you configure additional 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.

Highlighting nested paths

By default, a LinkMenuItem is highlighted only when the current path matches its href exactly. Apps with deeply nested routes often need the item to stay highlighted on child routes as well. For example, you might want Projects to stay highlighted while the user navigates to /projects/alpha/boards/3.

The activePath prop takes a glob pattern, or an array of glob patterns, that the platform matches against the current path. If any pattern matches, the item is highlighted. Matching against the item's own href still applies, so you only need to describe the additional paths.

1
2
3
4
5
6
7
<LinkMenuItem
  label="Projects"
  href="/projects"
  icon="folder-closed"
  activePath="/projects/**"
/>

Patterns support the following wildcards:

Using icons

The icon prop accepts an ADS icon glyph name as a string. The platform renders the icon at the correct size and color for the sidebar context. Browse all available glyph names in the ADS icon explorer.

1
2
<LinkMenuItem label="Reports" href="/reports" icon="chart-bar" />

Use icons to help users identify destinations more quickly. Icons work alongside labels — they don't replace them.

Icon guidelines

Follow these guidelines when choosing icons for sidebar navigation:

1. Use icons that represent destinations, not actions. Choose icons for places your users navigate to, such as a dashboard, a reports area, or a settings section. Avoid icons that suggest transient actions like create, edit, or run — those belong in buttons and menus.

2. Always pair icons with labels. The icon prop should always appear alongside a label. Don't rely on an icon alone to communicate a destination — very few icons are universally understood, especially in a custom app context.

3. Maintain a one-to-one relationship between icons and destinations. Each icon should represent exactly one destination, and each destination should use exactly one icon. Duplicating an icon across two items, or swapping icons for the same item in different parts of the navigation, weakens recognition.

4. Be mindful of Atlassian's existing navigation icons. Some ADS icons are already associated with specific Atlassian products and navigation areas. Reusing them for unrelated destinations in your app can mislead users into thinking they are navigating to an Atlassian-native area.

Recommended icons to avoid in unrelated contexts

The following icons are used in Atlassian's own global navigation for specific primary objects and areas. We recommend avoiding them for destinations that are unrelated to the Atlassian product they represent.

ADS glyph name	ADS icon	Meaning	Guidance
"spaces"		Spaces directory in Confluence	Avoid if your destination isn't related to Confluence Spaces.
"project"		Projects directory in Jira	Avoid if your destination isn't related to Jira Projects.
"goal"		Goal object in the Goals app	Avoid if your destination isn't related to Atlassian Goals.
"dashboard"		Dashboard object in the Home app	Avoid if your destination isn't related to Atlassian Dashboards.
"teams"		Teams object in the Teams app	Avoid if your destination isn't related to Atlassian Teams.
"person"		"For you" landing page in Atlassian navigation	Avoid reusing this icon to prevent confusion with Atlassian's "For you" navigation item.
"clock"		"Recent" flyout in Atlassian navigation	Avoid to prevent confusion with Atlassian's "Recent" navigation item.
"star-starred", "star-unstarred"		"Starred" flyout in Atlassian navigation	Avoid unless your destination represents starred or favourited content.

MenuSection

Groups sidebar menu items under an optional section header. Use the label prop to display a section header above the items.

Adding a section header

Use MenuSection with a label prop to add a section header for menu items in the sidebar.

1
2
3
4
5
6
7
8
9
<Global>
  <Sidebar>
    <MenuSection label="Your homes">
      <LinkMenuItem label="Home 1" href="/home-1" />
      <LinkMenuItem label="Home 2" href="/home-2" />
    </MenuSection>
  </Sidebar>
</Global>

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.

1
2
3
4
5
6
7
8
{
  id: string;
  label: string;
  href: string;
  icon?: string;
  activePath?:
    string | string[]
}[]

1
2
3
(
  items: Item[]
) => void

1
2
3
4
5
(
  error: Error,
  currentItems: Item[],
  nextItems: Item[]
) => void

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>.
• Custom UI is not supported for global:ui. The platform enforces a UI chrome around the module and UI Kit is the public API that lets you control it. To embed custom web content in the main content area, use the Frame component inside <Main>.
• By default, the sidebar displays the platform-provided For you item as its first entry. This item navigates to the route /for-you and acts as the app's home page. Set forYouMenuItem to false to hide it; the app then uses the root route / as the home page.

Usage example

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
import React, { useState } from "react";
import ForgeReconciler, { Button, Text } from "@forge/react";
import {
  Global,
  Sidebar,
  LinkMenuItem,
  ExpandableMenuItem,
  MenuSection,
  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="Reports" href="/reports" icon="chart-bar" />
        <LinkMenuItem label="Recent" href="/recent" />

        <MenuSection label="Dashboards">
          <LinkMenuItem label="Sales performance" href="/reports/sales-performance" />
          <LinkMenuItem label="Team activity" href="/reports/team-activity" />
        </MenuSection>

        <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>
);

Using dispatch to update state

If using a Frame component in the Main content area of your app, there may be scenarios where you want to update the app state from within the Frame resource. You can use the dispatch prop to define a function that can be called inside the resource to dispatch updates to its parent.

The implementation of the function is up to you, although the most common pattern will be to use a reducer and its associated dispatch function. This is a pattern that will be familiar to developers who have used React’s useReducer hook or React Redux for complex state management.

Example

Main app

In the main app, the sidebar state is defined as a list of items that can be dynamically updated, with each item mapping to a LinkMenuItem component. The reducer is a pure function that updates the state based on a provided action, which it receives when dispatch is called.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
import React, { useReducer } from "react";
import ForgeReconciler, { Frame } from "@forge/react";
import {
  Global,
  Sidebar,
  LinkMenuItem,
  LinkMenuItemProps,
  Main,
} from "@forge/react/global";

interface GlobalState {
  sidebar: LinkMenuItemProps[];
}

type AddSidebarItemAction = {
  type: "ADD_SIDEBAR_ITEM";
  item: LinkMenuItemProps;
};
const initialState: GlobalState = {
  sidebar: [
    { id: "dashboard", label: "Dashboard", href: "/dashboard" },
    { id: "bugs", label: "Bugs", href: "/bugs" },
    {
      id: "reports",
      label: "Reports",
      type: "expandable",
      children: [
        { id: "weekly", label: "Weekly", href: "/reports/weekly" },
        { id: "monthly", label: "Monthly", href: "/reports/monthly" },
      ],
    },
  ],
};

const reducer = (state: GlobalState, action: Action) => {
  switch (action.type) {
    case "ADD_SIDEBAR_ITEM":
      return {
        ...state,
        sidebar: [...state.sidebar, action.item],
      };
    default:
      return state;
  }
};

const App = () => {
  const [state, dispatch] = useReducer(reducer, initialState);

  return (
    <Global>
      <Sidebar>
        {state.sidebar.map((item) => (
          <LinkMenuItem key={item.id} {...item} />
        ))}
      </Sidebar>
      <Main>
        <Frame resource="my-resource" dispatch={dispatch} />
      </Main>
    </Global>
  );
};

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

my-resource

Inside the resource, the dispatch function can be retrieved by calling view.getFrameDispatch(). It can then be used to dispatch actions to the parent to trigger state updates. In this example, it adds a new Settings item to the sidebar menu.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import React, { useEffect, useState } from "react";
import { view } from "@forge/bridge";

const App = () => {
  const [dispatch, setDispatch] = useState(undefined);

  useEffect(() => {
    view
      .getFrameDispatch()
      // If using React to set the dispatch function in state to use, make sure to
      // wrap it in a callback. Otherwise React treats dispatch as a functional updater
      // and tries to execute it.
      .then((dispatch) => setDispatch(() => dispatch));
  }, []);

  if (!dispatch) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <button
        onClick={() =>
          dispatch({
            type: "ADD_SIDEBAR_ITEM",
            item: {
              id: "settings",
              label: "Settings",
              href: "/settings",
            },
          })
        }
      >
        Add Settings menu item
      </button>
    </div>
  );
};

export default App;