Merge pull request #31117 from Andy2003/feature/icons-for-tabs-on-entity-page

Add the ability to show icons for the tabs on the entity page (new frontend)
2026-02-05 22:56:26 +01:00
parent 884f6d9a63 c2b2de4fe1
commit 4ddc564e73
20 changed files with 508 additions and 198 deletions
@@ -696,3 +696,63 @@ filter:
      targetRef:
        $in: [group:default/admins, group:default/viewers]
 ```
+
+### Configure groups, titles, and icons
+
+You can define and customize the tab groups that appear on the entity page, as well as enable icons for both groups and individual tabs.
+
+```yaml
+app:
+  extensions:
+    # Entity page (new frontend system)
+    - page:catalog/entity:
+        config:
+          # Show icons next to group and tab titles
+          showNavItemIcons: true
+
+          # Optionally override default groups and their icons
+          groups:
+            - overview:
+                title: Overview
+                icon: dashboard
+            - quality:
+                title: Quality
+                icon: verified
+            - documentation:
+                title: Docs
+                icon: description
+```
+
+Notes:
+
+- Icons for groups and tabs are resolved via the app's IconsApi. When using a string icon id (for example `"dashboard"`), ensure that the corresponding icon bundles are enabled/installed in your app (see the [IconBundleBlueprint documentation](https://backstage.io/api/stable/variables/_backstage_plugin-app-react.IconBundleBlueprint.html)).
+- Group icons are only rendered if `showNavItemIcons` is set to `true`.
+
+### Overriding or disabling a tab's group (per extension)
+
+Each entity content extension (tabs on the entity page) can declare a default `group` in code. You can override or disable this per installation in `app-config.yaml` using the extension's config:
+
+```yaml
+app:
+  extensions:
+    # ...
+    # Example entity content extension instance id
+    - entity-content:example/my-content:
+        config:
+          # Move this tab to a custom group you defined above
+          group: custom
+          # Show an icon for this entity content page but only if `showNavItemIcons` is enabled for the `page:catalog/entity` extension
+          icon: my-icon
+
+    # Disassociate from any group and show as a standalone tab
+    - entity-content:example/another-content:
+        config:
+          group: false
+```
+
+### Tab icons for entity content
+
+Entity content extensions can also declare an `icon` parameter. When provided as a string, the icon id is looked up via the IconsApi. For the icon to render:
+
+- The entity page must have `showNavItemIcons: true` (see configuration above).
+- The icon id must be available in the app's enabled icon bundles.
@@ -73,6 +73,31 @@ Avoid using `convertLegacyEntityCardExtension` from `@backstage/core-compat-api`

 Creates entity content to be displayed on the entity pages of the catalog plugin. Exported as `EntityContentBlueprint`.

+Supports optional params such as `group` and `icon` to:
+
+- group: string | false — associates the content with a tab group on the entity page (for example "overview", "quality", "deployment", or any custom id). You can override or disable this per-installation via app-config using `app.extensions[...].config.group`, where `false` removes the grouping.
+- icon: string — sets the tab icon. Note: when providing a string, the icon is looked up via the app's IconsApi; make sure icon bundles are enabled/installed in your app (see the Icons blueprint reference above) so that the icon id you use is available.
+
+To render icons in the entity page tabs, the page must also have icons enabled via app configuration. Set `showNavItemIcons: true` on the catalog entity page config (created via `page:catalog/entity`). Example:
+
+```yaml
+app:
+  extensions:
+    # Entity page
+    - page:catalog/entity:
+        config:
+          # Enable tab- and group-icons
+          showNavItemIcons: true
+          # Optionally override default groups and their icons
+          groups:
+            - overview:
+                title: Overview
+                icon: dashboard
+            - documentation:
+                title: Docs
+                icon: description
+```
+
 Avoid using `convertLegacyEntityContentExtension` from `@backstage/core-compat-api` to convert legacy entity content extensions to the new system. Instead, use the `EntityContentBlueprint` directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.

 ## Extension blueprints in `@backstage/plugin-search-react/alpha`