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';
Then replace the default themes in the createApp configuration:
const app = createApp({
// ... other config
themes: [
{
id: 'my-theme',
title: 'My Custom Theme',
variant: 'light',
Provider: ({ children }) => (
<UnifiedThemeProvider theme={myCustomTheme} children={children} />
),
},
],
});
Restart Backstage and observe the new colors in the sidebar and page headers.
Tip
Try changing theprimary.main and navigation.background colors to match your company’s brand. You can use any valid CSS color value.Task 6.2: Create a Custom Home Page
Now let’s replace the default home page with a custom one.
Create packages/app/src/components/home/HomePage.tsx:
import { Content, Header, Page } from '@backstage/core-components';
import { Grid, Typography, Box } from '@material-ui/core';
import { makeStyles } from '@material-ui/core/styles';
const useStyles = makeStyles((theme) => ({
congratsContainer: {
textAlign: 'center',
padding: theme.spacing(8, 2),
},
logo: {
marginBottom: theme.spacing(4),
},
message: {
marginTop: theme.spacing(3),
color: theme.palette.text.secondary,
},
}));
export const HomePage = () => {
const classes = useStyles();
return (
<Page themeId="home">
<Header title="Welcome to Your Developer Portal" />
<Content>
<Grid container spacing={3}>
<Grid item xs={12}>
<Box className={classes.congratsContainer}>
<div className={classes.logo}>
<svg width="310px" height="80px" viewBox="0 0 310 80" version="1.1" xmlns="http://www.w3.org/2000/svg">
<title>Puzzle ITC</title>
<g stroke="none" strokeWidth="1" fill="none" fillRule="evenodd">
<g fill="#9CC9FF">
<path d="M102.863636,42.8364912 L107.93011,42.8364912 C109.403315,42.8364912 110.526696,42.4336842 111.296028,41.6245614 C112.066769,40.8161404 112.451787,39.7775439 112.451787,38.5080702 C112.451787,37.2112281 112.066769,36.1494737 111.296028,35.3214035 C110.526696,34.4926316 109.403315,34.0785965 107.93011,34.0785965 L102.863636,34.0785965 L102.863636,42.8364912 Z M102.863636,48.0477193 L102.863636,58.0477193 L96.0494474,58.0477193 L96.0494474,28.8673684 L107.93011,28.8673684 C111.400201,28.8673684 114.154454,29.7536842 116.190757,31.522807 C118.229172,33.2947368 119.247675,35.6091228 119.247675,38.4680702 C119.247675,41.3410526 118.229172,43.6561404 116.190757,45.4133333 C114.154454,47.1691228 111.400201,48.0477193 107.93011,48.0477193 L102.863636,48.0477193 Z M146.12434,28.8675088 L146.12434,47.9875088 C146.12434,51.3152281 145.015037,53.8934737 142.797135,55.7243509 C140.579937,57.5538246 137.675056,58.4682105 134.084602,58.4682105 C130.452621,58.4682105 127.524511,57.5538246 125.29957,55.7243509 C123.075333,53.8934737 121.961807,51.3152281 121.961807,47.9875088 L121.961807,28.8675088 L128.7767,28.8675088 L128.7767,47.9875088 C128.7767,49.778386 129.239848,51.104 130.164033,51.9664561 C131.088217,52.826807 132.395308,53.258386 134.084602,53.258386 C135.759115,53.258386 137.047905,52.8310175 137.953085,51.9755789 C138.857561,51.1201404 139.309447,49.7910175 139.309447,47.9875088 L139.309447,28.8675088 L146.12434,28.8675088 Z M157.164298,52.8378246 L170.492826,52.8378246 L170.492826,58.0476491 L148.802293,58.0476491 L148.802293,55.0020351 L161.88869,34.0785263 L148.742464,34.0785263 L148.742464,28.8672982 L170.312635,28.8672982 L170.312635,31.793614 L157.164298,52.8378246 Z M180.981159,52.8378246 L194.308984,52.8378246 L194.308984,58.0476491 L172.619859,58.0476491 L172.619859,55.0020351 L185.706255,34.0785263 L172.558622,34.0785263 L172.558622,28.8672982 L194.128792,28.8672982 L194.128792,31.793614 L180.981159,52.8378246 Z M203.672106,52.8378246 L216.275646,52.8378246 L216.275646,58.0476491 L196.856509,58.0476491 L196.856509,28.8672982 L203.672106,28.8672982 L203.672106,52.8378246 Z M236.928671,45.5626667 L225.449919,45.5626667 L225.449919,52.8377544 L238.978348,52.8377544 L238.978348,58.0475789 L218.636434,58.0475789 L218.636434,28.8672281 L239.018468,28.8672281 L239.018468,34.0784561 L225.449919,34.0784561 L225.449919,40.3514386 L236.928671,40.3514386 L236.928671,45.5626667 Z M259.540995,58.0477193 L252.766927,58.0477193 L252.766927,28.8673684 L259.540995,28.8673684 L259.540995,58.0477193 Z M284.27099,34.0785965 L276.551621,34.0785965 L276.551621,58.0477193 L269.736728,58.0477193 L269.736728,34.0785965 L262.078596,34.0785965 L262.078596,28.8673684 L284.27099,28.8673684 L284.27099,34.0785965 Z M309.071513,47.8077193 L309.111634,47.9270175 C308.977195,51.3480702 307.960803,53.9592982 306.065978,55.7642105 C304.167634,57.5677193 301.418308,58.4680702 297.813778,58.4680702 C294.195873,58.4680702 291.25439,57.3592982 288.989329,55.1417544 C286.724267,52.9242105 285.591737,50.0449123 285.591737,46.5045614 L285.591737,40.4119298 C285.591737,36.8842105 286.679923,34.0084211 288.859113,31.7845614 C291.036894,29.56 293.865757,28.4470175 297.352037,28.4470175 C301.050183,28.4470175 303.876935,29.3761404 305.832292,31.2322807 C307.791169,33.0905263 308.895545,35.7284211 309.150347,39.1494737 L309.111634,39.2694737 L302.497345,39.2694737 C302.403026,37.3719298 301.977887,35.962807 301.22052,35.0407018 C300.463857,34.1185965 299.172955,33.6575439 297.352037,33.6575439 C295.809853,33.6575439 294.597081,34.2757895 293.712313,35.5122807 C292.828953,36.7487719 292.386217,38.3677193 292.386217,40.3719298 L292.386217,46.5045614 C292.386217,48.5221053 292.869074,50.1529825 293.834083,51.394386 C294.798388,52.6378947 296.124484,53.2589474 297.813778,53.2589474 C299.448873,53.2589474 300.608151,52.8238596 301.291611,51.9550877 C301.974368,51.0877193 302.363609,49.7045614 302.45652,47.8077193 L309.071513,47.8077193 Z M11.6887872,68.3477193 C-3.89635626,52.8101754 -3.89635626,27.62 11.6887872,12.0831579 C27.2711153,-3.45298246 52.538728,-3.4522807 68.1217599,12.0831579 C83.7061995,27.6214035 83.7047918,52.8087719 68.1217599,68.3463158 C52.5380241,83.8838596 27.2732269,83.8852632 11.6887872,68.3477193 Z M38.8588264,45.0983158 C38.8588264,45.0983158 46.0411408,44.086386 48.1161567,40.0884912 C50.1925804,36.0934035 52.6378333,27.9951579 52.6378333,27.9951579 C41.5792934,27.9944561 40.593872,31.8569123 40.593872,31.8569123 C40.593872,31.8569123 33.6044187,51.3411228 31.1120064,58.5298947 C11.746364,58.5298947 14.8412911,48.9930526 14.8412911,48.9930526 L24.5279836,21.9011228 L44.1533549,21.9011228 L42.8427444,25.8028772 C42.8427444,25.8028772 44.4419426,21.9011228 55.2583503,21.9011228 C55.2583503,21.9011228 66.3471567,21.9495439 65.0442888,25.8232281 C63.7435326,29.6955088 59.5604187,41.3123509 59.5604187,41.3123509 C58.1611203,45.0983158 49.97438,45.0653333 38.8588264,45.0983158 Z"></path>
</g>
</g>
</svg>
</div>
<Typography variant="h3" gutterBottom>
🎉 Congratulations! 🎉
</Typography>
<Typography variant="h5" className={classes.message}>
You have successfully completed the Backstage Techlab!
</Typography> <Route path="/" element={<HomePage />} />
<Typography variant="body1" className={classes.message}>
You've learned how to set up, customize, and extend Backstage to create
an amazing developer portal. Keep exploring and building!
</Typography>
</Box>
</Grid>
</Grid>
</Content>
</Page>
);
};
Update the Sidebar navigation entries:
# In packages/app/src/components/root/Root.tsx
<SidebarItem icon={HomeIcon} to="/" text="Home" />
<SidebarItem icon={CatalogIcon} to="catalog" text="Catalog" />
Set the route element in App.tsx:
<Route path="/" element={<HomePage />} />
After restarting, the root URL / will now show your custom home page instead of the default catalog view.
Summary
In this chapter, you:
- ✅ Customized the Backstage theme with your own colors and page themes
- ✅ Created a custom home page component
- ✅ Updated the sidebar navigation and routing
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.