Skip to main content
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.
The image is a diagram titled "Backstage Design System," showing two components: "Backstage UI/UX" and "Material UI."

​
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>
  </>
);
Browse the full list of Backstage and Material-UI components in the Backstage Storybook.

​
Exploring Backstage Components

Backstage publishes its components in Storybook. You’ll find cards, progress bars, navigation elements, and more—all ready to customize.
The image shows a user interface with a sidebar menu and four progress cards displaying percentages (30%, 57%, 89%, and 20%) in circular progress bars. The theme is set to "Light theme."
Component TypeDescriptionExample Usage
CardContainer for grouped content<Card><CardContent>...</CardContent></Card>
Progress CircleVisualize task completion percentage<CircularProgress variant="determinate" value={50} />
SidebarNavigation wrapper for main sections<Sidebar><SidebarItem to="/">Home</SidebarItem></Sidebar>

​
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.
The image is a design theme guide showing different color palettes, typography, shadow effects, and element opacity options. It includes background, primary, and secondary colors, along with font and shadow settings.

​
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.
Using a nonstandard font like Comic Sans MS may impact readability. Choose a web-safe or hosted font for production.

​
Applying the Theme with React Context

Backstage uses React Context to make the theme available to all components. Wrap your root app with ThemeProvider:
The image is a flowchart illustrating a React component hierarchy for changing themes, starting with "themeProvider" and "app" at the top, followed by "home," and branching into "SideBar," "Catalog," and "Search."
// 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.

Watch Video