6. Change the Look and Feel

Backstage is designed to be branded and customized to match your organization’s identity. In this chapter, you’ll learn how to customize the theme (colors, fonts, logo), create a custom home page, and adjust the navigation sidebar. These changes help make the developer portal feel like an integral part of your company’s toolchain rather than a generic off-the-shelf product.

Note

Backstage uses Material UI (MUI) for its component library. Theme customizations follow the MUI theming approach, so if you’re familiar with MUI, you’ll feel right at home.

Task 6.1: Customize the Theme

Backstage supports custom themes to align the portal with your corporate design. You can override colors, typography, and more.

Step 1: Create a custom theme

Create a new file packages/app/src/theme.ts:

import {
  createUnifiedTheme,
  palettes,
  genPageTheme,
  shapes,
} from '@backstage/theme';

export const myCustomTheme = createUnifiedTheme({
  palette: {
    ...palettes.light,
    primary: {
      main: '#0052CC',
    },
    secondary: {
      main: '#FF5630',
    },
    navigation: {
      background: '#172B4D',
      indicator: '#0052CC',
      color: '#FFFFFF',
      selectedColor: '#FFFFFF',
    },
  },
  defaultPageTheme: 'home',
  pageTheme: {
    home: genPageTheme({
      colors: ['#0052CC', '#00B8D9'],
      shape: shapes.wave,
    }),
    documentation: genPageTheme({
      colors: ['#6554C0', '#00B8D9'],
      shape: shapes.wave2,
    }),
    tool: genPageTheme({
      colors: ['#FF5630', '#FFAB00'],
      shape: shapes.round,
    }),
  },
});

Step 2: Apply the theme

Edit packages/app/src/App.tsx and wrap the app with your custom theme.

Add the import:

import { UnifiedThemeProvider } from '@backstage/theme';
import { myCustomTheme } from './theme';
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { ThemeBlueprint } from '@backstage/plugin-app-react';

Then add a createFrontendModule function and extend the createApp configuration to use it:

const themeModule = createFrontendModule({
  pluginId: 'app',
  extensions: [
    ThemeBlueprint.make({
      name: 'my-custom-theme',
      params: {
        theme: {
          id: 'my-custom-theme',
          title: 'My Custom Theme',
          variant: 'light',
          Provider: ({ children }) => (
            <UnifiedThemeProvider theme={myCustomTheme}>
              {children}
            </UnifiedThemeProvider>
          ),
        },
      },
    }),
  ],
});


export default createApp({
  features: [..., themeModule],
});

Restart Backstage

When you check Settings -> Appearance, you should see your new theme. Select you theme and observe the new colors in the sidebar and page headers.

Tip

Try changing the primary.main and navigation.background colors to match your company’s brand. You can use any valid CSS color value.

Summary

In this chapter, you:

✅ Customized the Backstage theme with your own colors and page themes

These customizations make Backstage feel like a native part of your organization’s tooling. In a real-world setup, you would further refine the theme to match your corporate design guidelines and add useful widgets (e.g., quick links, recent components, announcements) to the home page.

Last modified June 9, 2026: update lab 6 (0fcafe1)