diff --git a/docs/conf/user-interface/icons--old.md b/docs/conf/user-interface/icons--old.md
new file mode 100644
index 0000000000..4a2ede9ec9
--- /dev/null
+++ b/docs/conf/user-interface/icons--old.md
@@ -0,0 +1,121 @@
+---
+id: icons--old
+title: Customizing Icons (Old Frontend System)
+sidebar_label: Icons
+description: Learn how to customize and add icons to your Backstage app using the old frontend system.
+---
+
+::::info
+This documentation is for Backstage apps that still use the old frontend
+system. If your app uses the new frontend system, read the
+[current guide](./icons.md) instead.
+::::
+
+Backstage comes with a set of [default icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx) used throughout the app, for example in the sidebar, entity links, and catalog kind badges. You can override any of these icons or register additional ones to match your organization's visual identity.
+
+In the old frontend system, icons are supplied directly to the `createApp`
+call in `packages/app/src/App.tsx`.
+
+## Custom icons
+
+### Requirements
+
+- Files in `.svg` format or any image format that can be rendered as a React
+ component.
+- React components created for the icons.
+
+### Create a React component
+
+In your frontend application, locate the `src` folder. Create an
+`assets/icons` directory and a `customIcons.tsx` file:
+
+```tsx title="packages/app/src/assets/icons/customIcons.tsx"
+import { SvgIcon, SvgIconProps } from '@material-ui/core';
+
+export const ExampleIcon = (props: SvgIconProps) => (
+
+
+
+);
+```
+
+### Use the custom icon
+
+Supply your custom icon in `packages/app/src/App.tsx`:
+
+```tsx title="packages/app/src/App.tsx"
+import { ExampleIcon } from './assets/icons/customIcons';
+
+const app = createApp({
+ apis,
+ themes: [
+ /* ... */
+ ],
+ icons: {
+ github: ExampleIcon,
+ },
+ bindRoutes({ bind }) {
+ /* ... */
+ },
+});
+```
+
+## Adding icons
+
+If the [default icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx) do not cover your needs, you can register additional icons so that they
+can be referenced in places like entity links. For this example we use the
+`AlarmIcon` from [Material UI](https://v4.mui.com/components/material-icons/):
+
+```tsx title="packages/app/src/App.tsx"
+import AlarmIcon from '@material-ui/icons/Alarm';
+
+const app = createApp({
+ apis,
+ icons: {
+ alert: AlarmIcon,
+ },
+ themes: [
+ /* ... */
+ ],
+});
+```
+
+You can then reference `alert` as the icon in entity links:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: artist-lookup
+ description: Artist Lookup
+ links:
+ - url: https://example.com/alert
+ title: Alerts
+ icon: alert
+```
+
+And this is the result:
+
+
+
+### Using icons in plugin code
+
+In the old frontend system, retrieve icons from the app context:
+
+```ts
+import { useApp } from '@backstage/core-plugin-api';
+
+const app = useApp();
+const alertIcon = app.getSystemIcon('alert');
+```
+
+This is useful when you have an icon that you want to render in several
+locations within a plugin.
+
+:::note
+If an icon key is not available as a default icon or one you have added, it
+falls back to Material UI's `LanguageIcon`.
+:::
diff --git a/docs/conf/user-interface/icons.md b/docs/conf/user-interface/icons.md
index 26a6f11096..2e8b0dd466 100644
--- a/docs/conf/user-interface/icons.md
+++ b/docs/conf/user-interface/icons.md
@@ -2,123 +2,154 @@
id: icons
title: Customizing Icons
sidebar_label: Icons
-description: Customizing Icons
+description: Learn how to customize and add icons to your Backstage app.
---
-So far you've seen how to create your own theme and add your own logo, in the following sections you'll be shown how to override the existing icons and how to add more icons
+::::info
+This documentation is written for the new frontend system, which is the default
+in new Backstage apps. If your Backstage app still uses the old frontend system,
+read the [old frontend system version of this guide](./icons--old.md) instead.
+::::
-## Custom Icons
+Backstage comes with a set of [default icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx) used throughout the app, for example in the sidebar, entity links, and catalog kind badges. You can override any of these icons or register additional ones to match your organization's visual identity.
-You can also customize the Project's _default_ icons.
+## Custom icons
-You can change the following [icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx).
+To override a default icon, create an icon bundle extension using
+`IconBundleBlueprint` from `@backstage/plugin-app-react`. Each entry in the
+`icons` object maps an icon key to a React component or JSX element that
+replaces the built-in icon with the same key.
### Requirements
-- Files in `.svg` format
-- React components created for the icons
+- Files in `.svg` format or any image format that can be rendered as a React
+ component.
+- React components created for the icons, or `IconElement` JSX elements.
-### Create React Component
+### Create a React component
-In your front-end application, locate the `src` folder. We suggest creating the `assets/icons` directory and `customIcons.tsx` file.
+In your frontend application, locate the `src` folder. Create an
+`assets/icons` directory and a `customIcons.tsx` file:
-```tsx title="customIcons.tsx"
+```tsx title="packages/app/src/assets/icons/customIcons.tsx"
import { SvgIcon, SvgIconProps } from '@material-ui/core';
export const ExampleIcon = (props: SvgIconProps) => (
);
```
-### Using the custom icon
+### Use the custom icon
-Supply your custom icon in `packages/app/src/App.tsx`
+Supply your custom icon in `packages/app/src/App.tsx` by creating an icon
+bundle extension and installing it as a module for the `app` plugin:
```tsx title="packages/app/src/App.tsx"
-/* highlight-add-next-line */
-import { ExampleIcon } from './assets/icons/CustomIcons'
+import { createApp } from '@backstage/frontend-defaults';
+import { createFrontendModule } from '@backstage/frontend-plugin-api';
+import { IconBundleBlueprint } from '@backstage/plugin-app-react';
+import { ExampleIcon } from './assets/icons/customIcons';
+const customIconBundle = IconBundleBlueprint.make({
+ name: 'custom-icons',
+ params: {
+ icons: {
+ github: ,
+ },
+ },
+});
const app = createApp({
- apis,
- components: {
- {/* ... */}
- },
- themes: [
- {/* ... */}
+ features: [
+ createFrontendModule({
+ pluginId: 'app',
+ extensions: [customIconBundle],
+ }),
],
- /* highlight-add-start */
- icons: {
- github: ExampleIcon,
- },
- /* highlight-add-end */
- bindRoutes({ bind }) {
- {/* ... */}
- }
-})
+});
+
+export default app.createRoot();
```
-## Adding Icons
+The `icons` object maps icon keys to React components or JSX elements. In this
+example, the built-in `github` icon is replaced with `ExampleIcon`. You can
+override multiple icons at once by adding more entries to the object.
-You can add more icons, if the [default icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx) do not fit your needs, so that they can be used in other places like for Links in your entities. For this example we'll be using icons from[Material UI](https://v4.mui.com/components/material-icons/) and specifically the `AlarmIcon`. Here's how to do that:
+The module can also be declared in a separate module package if you prefer to
+keep icon customizations separate from your app setup.
-1. First you will want to open your `App.tsx` in `/packages/app/src`
-2. Then you want to import your icon, add this to the rest of your imports: `import AlarmIcon from '@material-ui/icons/Alarm';`
-3. Next you want to add the icon like this to your `createApp`:
+## Adding icons
- ```tsx title="packages/app/src/App.tsx"
- const app = createApp({
- apis: ...,
- plugins: ...,
- /* highlight-add-start */
- icons: {
- alert: AlarmIcon,
- },
- /* highlight-add-end */
- themes: ...,
- components: ...,
- });
- ```
+If the [default icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx) do not cover your needs, you can register additional icons so that they
+can be referenced in places like entity links. For this example we use the
+`RiAlarmLine` icon from [Remix Icon](https://remixicon.com/), declared as a JSX
+element:
-4. Now we can reference `alert` for our icon in our entity links like this:
+```tsx title="packages/app/src/App.tsx"
+import { createApp } from '@backstage/frontend-defaults';
+import { createFrontendModule } from '@backstage/frontend-plugin-api';
+import { RiAlarmLine } from '@remixicon/react';
+import { IconBundleBlueprint } from '@backstage/plugin-app-react';
- ```yaml
- apiVersion: backstage.io/v1alpha1
- kind: Component
- metadata:
- name: artist-lookup
- description: Artist Lookup
- links:
- - url: https://example.com/alert
- title: Alerts
- icon: alert
- ```
+const extraIcons = IconBundleBlueprint.make({
+ name: 'extra-icons',
+ params: {
+ icons: {
+ alert: ,
+ },
+ },
+});
- And this is the result:
+const app = createApp({
+ features: [
+ createFrontendModule({
+ pluginId: 'app',
+ extensions: [extraIcons],
+ }),
+ ],
+});
- 
+export default app.createRoot();
+```
- Another way you can use these icons is from the `AppContext` like this:
+You can then reference `alert` as the icon in entity links:
- ```ts
- import { useApp } from '@backstage/core-plugin-api';
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: artist-lookup
+ description: Artist Lookup
+ links:
+ - url: https://example.com/alert
+ title: Alerts
+ icon: alert
+```
- const app = useApp();
- const alertIcon = app.getSystemIcon('alert');
- ```
+And this is the result:
- You might want to use this method if you have an icon you want to use in several locations.
+
-:::note Note
+### Using icons in plugin code
-If the icon is not available as one of the default icons or one you've added then it will fall back to Material UI's `LanguageIcon`
+To look up a registered icon at runtime, use the `IconsApi`:
+```ts
+import { useApi, iconsApiRef } from '@backstage/frontend-plugin-api';
+
+const iconsApi = useApi(iconsApiRef);
+const alertIcon = iconsApi.icon('alert');
+```
+
+This is useful when you have an icon that you want to render in several
+locations within a plugin.
+
+:::note
+If an icon key is not available as a default icon or one you have added, a
+fallback icon is used instead.
:::