Customizing UI

In this guide, we’ll show you how to customize the Backstage user interface by leveraging its design system, theming capabilities, and React Context integration. You’ll learn how to integrate Material-UI, explore prebuilt Backstage components, create a custom theme, and apply it across your app.

Backstage Design System

Backstage’s design system builds on top of Material-UI and Backstage’s own component library. All Material-UI components work seamlessly alongside Backstage’s custom elements—giving you a consistent look and feel.

Material-UI Integration

Material-UI provides prebuilt React components—buttons, cards, sliders, etc.—that you can drop right into your Backstage frontend.

Install the core packages:

npm install @mui/material @emotion/react @emotion/styled

Then import and use the components:

import Button from '@mui/material/Button';
import ShoppingCartRounded from '@mui/icons-material/ShoppingCartRounded';

export const MyButtons = () => (
  <>
    <Button variant="text" startIcon={<ShoppingCartRounded />}>
      Add item
    </Button>
    <Button variant="contained" startIcon={<ShoppingCartRounded />}>
      Add item
    </Button>
    <Button variant="outlined" startIcon={<ShoppingCartRounded />}>
      Add item
    </Button>
  </>
);

Exploring Backstage Components

Backstage publishes its components in Storybook. You’ll find cards, progress bars, navigation elements, and more—all ready to customize.

Theming in Backstage

A theme defines colors, typography, shadows, and opacity. Backstage supports multiple themes (light/dark) so you can match your brand or user preferences.

Creating a Custom Theme

1. In your frontend app directory, navigate to packages/apps/<your-app>/src.
2. Create a theme/ folder and add myTheme.ts.

Define your theme using Backstage theming utilities:

// packages/apps/<your-app>/src/theme/myTheme.ts
import {
  createUnifiedTheme,
  createBaseThemeOptions,
  palettes,
} from '@backstage/theme';

export const myTheme = createUnifiedTheme({
  ...createBaseThemeOptions({
    palette: palettes.light,
  }),
  fontFamily: 'Comic Sans MS',     // Custom font
  defaultPageTheme: 'home',         // Default layout style
});

Custom Color Overrides

Override specific palette values for a unique look:

export const funTheme = createUnifiedTheme({
  ...createBaseThemeOptions({
    palette: {
      ...palettes.light,
      mode: 'light',
      primary: { main: '#e30777' },
      secondary: { main: '#f50057' },
    },
  }),
});

These colors will propagate to Buttons, Links, Charts, and other components.

Applying the Theme with React Context

Backstage uses React Context to make the theme available to all components. Wrap your root app with ThemeProvider:

// packages/apps/<your-app>/src/App.tsx
import React from 'react';
import { ThemeProvider } from '@backstage/core-components';
import { myTheme } from './theme/myTheme';
import { AppRoutes } from './AppRoutes';

export const App = () => (
  <ThemeProvider theme={myTheme}>
    <AppRoutes />
  </ThemeProvider>
);

By wrapping AppRoutes in ThemeProvider, the myTheme object is shared throughout your component tree—allowing consistent styling based on your custom theme.

Next Steps

Now you’re ready to:

• Integrate Material-UI components into Backstage.
• Browse and customize Backstage Storybook components.
• Define custom themes that match your brand.
• Apply them across your app using React Context.

Links and References

• Backstage Documentation
• Backstage Theme API
• Material-UI Documentation