Edit

Customize the look-and-feel of your App

Backstage ships with a default theme with a light and dark mode variant. The themes are provided as a part of the @backstage/theme package, which also includes utilities for customizing the default theme, or creating completely new themes.

Creating a Custom Theme

The easiest way to create a new theme is to use the createTheme function exported by the @backstage/theme package. You can use it to override so basic parameters of the default theme such as the color palette and font.

For example, you can create a new theme based on the default light theme like this:

import { createTheme, lightTheme } from '@backstage/theme';

const myTheme = createTheme({
  palette: lightTheme.palette,
  fontFamily: 'Comic Sans MS',
  defaultPageTheme: 'home',
});

If you want more control over the theme, and for example customize font sizes and margins, you can use the lower-level createThemeOverrides function exported by @backstage/theme in combination with createMuiTheme from @material-ui/core. See the @backstage/theme source and the implementation of the createTheme function for how this is done.

You can also create a theme from scratch that matches the BackstageTheme type exported by @backstage/theme. See the material-ui docs on theming for more information about how that can be done.

Using your Custom Theme

To add a custom theme to your Backstage app, you pass it as configuration to createApp.

For example, adding the theme that we created in the previous section can be done like this:

import { createApp } from '@backstage/core';

const app = createApp({
  apis: ...,
  plugins: ...,
  themes: [{
    id: 'my-theme',
    title: 'My Custom Theme',
    variant: 'light',
    theme: myTheme,
  }]
})

Note that your list of custom themes overrides the default themes. If you still want to use the default themes, they are exported as lightTheme and darkTheme from @backstage/theme.

Example of a custom theme

const themeOptions = createThemeOptions({
  palette: {
    ...lightTheme.palette,
    primary: {
      main: '#123456',
    },
    secondary: {
      main: '#123456',
    },
    error: {
      main: '#123456'
    },
    warning: {
      main: '#123456',
    },
    info: {
      main: '#123456',
    },
    success: {
      main: '#123456',
    },
    background: {
      default: '#123456',
      paper: '#123456',
    },
    banner: {
      info: '#123456',
      error: '#123456'
      text: '#123456'
      link: '#123456',
    },
    errorBackground: '#123456'
    warningBackground: '#123456'
    infoBackground: '#123456'
    navigation: {
      background: '#123456',
      indicator: '#123456'
      color: '#123456'
      selectedColor: '#123456',
    },
  },
  defaultPageTheme: 'home',
  fontFamily: 'Comic Sans',
  /* below drives the header colors */
  pageTheme: {
    home: genPageTheme(['#123456','#123456'], shapes.wave),
    documentation: genPageTheme(['#123456','#123456'], shapes.wave2),
    tool: genPageTheme(['#123456','#123456'], shapes.round),
    service: genPageTheme(['#123456','#123456'], shapes.wave),
    website: genPageTheme(['#123456','#123456'], shapes.wave),
    library: genPageTheme(['#123456','#123456'] shapes.wave),
    other: genPageTheme(['#123456','#123456'], shapes.wave),
    app: genPageTheme(['#123456','#123456'], shapes.wave),
    apis: genPageTheme(['#123456','#123456'], shapes.wave),
  },
});