Installation

Import BUI's global styles#

Backstage UI works by importing a global CSS file at the root of your application. This file includes all the default styles for the components. First, you'll need to install the package using a package manager. For example, if you're using Yarn:

yarn add @backstage/ui

import '@backstage/cli/asset-types';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@backstage/ui/css/styles.css'; 

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

Use BUI components#

As a plugin maintainer, you can use BUI components in your plugin. As mentioned above, you should not import the styles again in your plugin as this will be handled at the root of your application. To get started, just add the library to your plugin and import the components you need.

yarn add @backstage/ui

import { Flex, Button, Text } from '@backstage/ui';

<Flex>
  <Text>Hello World</Text>
  <Button>Click me</Button>
</Flex>;

BUIProvider#

BUIProvider provides routing and analytics integration for all BUI components. It must be rendered inside a React Router context for client-side navigation to work in components like Link, ButtonLink, Tabs, Menu, TagGroup, and Table.

Setup#

If you're using the new frontend system, the provider is wired automatically via @backstage/plugin-app — no setup required.

For the old frontend system, the BUIProvider is included in the app shell from @backstage/core-app-api and works out of the box.

If you need to set up the provider manually (e.g. in a custom app shell), wrap your app content with the BUIProvider inside your Router and pass in Backstage's useAnalytics hook:

import { BUIProvider } from '@backstage/ui';
import { useAnalytics } from '@backstage/core-plugin-api';
import { BrowserRouter } from 'react-router-dom';

// BUIProvider must be inside a Router for client-side navigation
<BrowserRouter>
  <BUIProvider useAnalytics={useAnalytics}>
    <AppContent />
  </BUIProvider>
</BrowserRouter>

Analytics#

Once configured, BUI components with navigation behavior — Link, ButtonLink, Tab, MenuItem, Tag, and Row — fire a click event through Backstage's analytics system when a user navigates. Events include the link text as the subject and the destination URL in the attributes, along with any AnalyticsContext metadata (such as pluginId) from the component's position in the tree.

To suppress tracking on an individual component, use the noTrack prop:

// Suppress analytics for a specific link
<Link href="/internal" noTrack>
  Skip tracking
</Link>