Router (Preview)

To add the Router and Route components to your app:

1
2
import { Router, Route } from '@forge/react/router';

Description

The Router component provides client-side routing for Forge UI Kit full page apps. It initializes a history instance using the Forge bridge and manages navigation state, allowing you to define routes and navigate between different views within your app without full page reloads.

Router works together with the Route component to render content based on the current URL path, and with the useNavigate, useLocation, and useParams hooks to programmatically navigate and read routing information.

Supported modules

The Router component can be used in the following modules:

• Bitbucket project settings menu page
• Bitbucket repository main menu page
• Bitbucket repository settings menu page
• Bitbucket workspace global page
• Bitbucket workspace personal settings page
• Bitbucket workspace settings menu page
• Confluence global page
• Confluence global settings
• Confluence space page
• Confluence space settings
• Jira admin page
• Jira global page
• Jira project page
• Jira project settings page

Router props

Route

The Route component conditionally renders its children when the current URL path matches its path prop. It must be used within a Router component.

When multiple Route components are placed as siblings inside a Router, only the first matching route is rendered.

Route paths support three types of segments:

• Static segments — Match a path segment exactly (e.g. /settings).
• Dynamic parameters — Segments prefixed with : capture a value from the URL (e.g. /posts/:id). Use the useParams hook to read captured values.
• Catch-all (*) — Matches any remaining path segments. The matched remainder is available as * in the params object.

Route props

Examples

Basic routing

Define multiple routes within a Router. Only the first matching Route is rendered.

1
2
import ForgeReconciler, { Text, Heading } from '@forge/react';
import { Router, Route } from '@forge/react/router';

const HomePage = () => (
  <>
    <Heading as="h1">Home</Heading>
    <Text>Welcome to the app!</Text>
  </>
);

const SettingsPage = () => (
  <>
    <Heading as="h1">Settings</Heading>
    <Text>Manage your preferences here.</Text>
  </>
);

const App = () => (
  <Router>
    <Route path="/">
      <HomePage />
    </Route>
    <Route path="/settings">
      <SettingsPage />
    </Route>
  </Router>
);

ForgeReconciler.render(<App />);

With a fallback

Use the fallback prop to show a loading indicator while the router initializes.

1
2
import ForgeReconciler, { Text, Spinner } from '@forge/react';
import { Router, Route } from '@forge/react/router';

const App = () => (
  <Router fallback={<Spinner label="Loading..." />}>
    <Route path="/">
      <Text>Home Page</Text>
    </Route>
  </Router>
);

ForgeReconciler.render(<App />);

Dynamic parameters

Use :paramName segments to capture dynamic values from the URL.

1
2
import ForgeReconciler, { Text } from '@forge/react';
import { Router, Route, useParams } from '@forge/react/router';

const PostDetail = () => {
  const { postId } = useParams();
  return <Text>Viewing post {postId}</Text>;
};

const App = () => (
  <Router>
    <Route path="/posts/:postId">
      <PostDetail />
    </Route>
  </Router>
);

ForgeReconciler.render(<App />);

Multiple dynamic parameters

Capture multiple values from the URL.

1
2
import ForgeReconciler, { Text } from '@forge/react';
import { Router, Route, useParams } from '@forge/react/router';

const CommentDetail = () => {
  const { postId, commentId } = useParams();
  return <Text>Post {postId}, Comment {commentId}</Text>;
};

const App = () => (
  <Router>
    <Route path="/posts/:postId/comments/:commentId">
      <CommentDetail />
    </Route>
  </Router>
);

ForgeReconciler.render(<App />);

Catch-all route (404 page)

Use a * path to catch any unmatched routes. Place it after all other routes. If a route path pattern ends with /*, it matches any characters following the /, including other / characters.

1
2
import ForgeReconciler, { Text } from '@forge/react';
import { Router, Route } from '@forge/react/router';

const App = () => (
  <Router>
    <Route path="/">
      <Text>Home</Text>
    </Route>
    <Route path="/settings">
      <Text>Settings</Text>
    </Route>
    <Route path="/*">
      <Text>Page not found</Text>
    </Route>
  </Router>
);

ForgeReconciler.render(<App />);