Skip to main content
Version: Next

Catalog Customization

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 instead.

The Backstage software catalog comes with a default catalog index page and entity pages that are highly configurable through app-config.yaml. This guide covers how to customize the catalog in the new frontend system.

Catalog index page​

The catalog index page can be configured through extensions in app-config.yaml. For example, to enable pagination:

app-config.yaml
app:
  extensions:
    - page:catalog:
        config:
          pagination: true

You can also configure pagination with additional options:

app-config.yaml
app:
  extensions:
    - page:catalog:
        config:
          pagination:
            mode: offset
            limit: 20

Configuring Catalog Export​

The catalog export feature is available in the new frontend system and can be enabled via the app-config.yaml. This will enable a button, which by default contains options to export data from the catalog table in CSV and JSON format. When exporting, a dialog opens that lets the user choose the export format and select which columns to include.

Basic Configuration​

To enable catalog export, add the following configuration:

app-config.yaml
app:
  extensions:
    - page:catalog:
        config:
          exportSettings:
            enabled: true
            # Optional: hide the built-in CSV and JSON formats, showing only your own supplied exporters
            disableBuiltinExporters: false

This will display an "Export selection" button on the catalog index page that allows users to export the currently filtered catalog entities in CSV or JSON format.

Advanced Configuration​

For advanced export customization like custom export formats, create a frontend module that provides a catalog export extension:

src/catalogExportExtension.tsx
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { CatalogExportConfigBlueprint } from '@backstage/plugin-catalog/alpha';
import type { CatalogExporter } from '@backstage/plugin-catalog';
import { catalogApiRef } from '@backstage/plugin-catalog-react';

// Define custom export formats using streaming async generators
const yamlExporter: CatalogExporter = ({ apis, columns, streamRequest }) => {
  const catalogApi = apis.get(catalogApiRef);

  // Return an async generator that yields YAML chunks
  async function* generateYaml() {
    for await (const page of catalogApi.streamEntities(streamRequest)) {
      for (const entity of page) {
        // Serialize each entity to YAML and yield immediately
        yield serializeEntityToYaml(entity, columns);
        yield '---\n'; // YAML document separator
      }
    }
  }

  return {
    generator: generateYaml(),
    contentType: 'application/x-yaml',
  };
};

// Create the extension using the blueprint
const catalogExportExtension = CatalogExportConfigBlueprint.make({
  params: {
    exporters: {
      yaml: { exporter: yamlExporter, label: 'YAML' },
    },
    columns: [{ entityFilterKey: 'metadata.name', title: 'Name' }],
    onSuccess: () => {
      console.log('Export successful!');
    },
    onError: ({ error }) => {
      console.error('Export failed:', error);
    },
  },
});

// Create the module that provides this extension
export default createFrontendModule({
  pluginId: 'catalog',
  extensions: [catalogExportExtension],
});

Then register this module in your app features:

packages/app-next/src/App.tsx
import catalogExportExtension from './catalogExportExtension';

const app = createApp({
  features: [
    // ... other features
    catalogExportExtension,
  ],
});

The CatalogExportConfigBlueprint supports the following properties:

  • exporters - Record of custom export format configurations (e.g., XML, YAML), each using the CatalogExporterConfig shape with an exporter function and optional label
  • columns - Custom columns to include in the export. Each column specifies an entity field path (entityFilterKey) and an optional display title. If not provided, defaults to Name, Type, Owner, and Description
  • onSuccess - Callback function invoked on successful export
  • onError - Callback function invoked if export fails, receives { error: Error }

Catalog filters​

The catalog index page includes a set of default filters (kind, type, owner, lifecycle, tag, namespace, processing status). These filters can be configured through extensions. For example, to set the initial kind filter:

app-config.yaml
app:
  extensions:
    - catalog-filter:catalog/kind:
        config:
          initialFilter: domain

To set the initial list filter to "all" instead of "owned":

app-config.yaml
app:
  extensions:
    - catalog-filter:catalog/list:
        config:
          initialFilter: all

Custom filters​

You can create custom catalog filters using the CatalogFilterBlueprint from @backstage/plugin-catalog-react/alpha. For example, to add a custom security tier filter:

packages/app/src/catalog/SecurityTierFilter.tsx
import { CatalogFilterBlueprint } from '@backstage/plugin-catalog-react/alpha';

export const securityTierFilter = CatalogFilterBlueprint.make({
  name: 'security-tier',
  params: {
    loader: async () => {
      const { EntitySecurityTierPicker } = await import(
        './EntitySecurityTierPicker'
      );
      return <EntitySecurityTierPicker />;
    },
  },
});

Then install it as a frontend module:

packages/app/src/catalog/catalogCustomizations.tsx
import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { securityTierFilter } from './SecurityTierFilter';

export default createFrontendModule({
  pluginId: 'catalog',
  extensions: [securityTierFilter],
});

Then register the module in your app:

packages/app/src/App.tsx
import { createApp } from '@backstage/frontend-defaults';
import catalogCustomizations from './catalog/catalogCustomizations';

const app = createApp({
  features: [catalogCustomizations],
});

export default app.createRoot();

Removing default filters​

Default filters can be disabled through app-config.yaml by setting them to false:

app-config.yaml
app:
  extensions:
    - catalog-filter:catalog/lifecycle: false
    - catalog-filter:catalog/tag: false
    - catalog-filter:catalog/processing-status: false

Customizing columns, actions, and table options​

In the old frontend system, customizing the catalog table columns, row actions, and table options was done by passing props directly to the CatalogIndexPage component. In the new frontend system, these customizations are done by overriding the page:catalog extension.

For example, to customize the catalog index page with custom columns or actions, you can override the page extension using a frontend module:

packages/app/src/catalog/customCatalogPage.tsx
import {
  PageBlueprint,
  createFrontendModule,
  createRouteRef,
} from '@backstage/frontend-plugin-api';

const customCatalogPage = PageBlueprint.make({
  params: {
    path: '/catalog',
    routeRef: createRouteRef({ aliasFor: 'catalog.catalogIndex' }),
    loader: async () => {
      const { CustomCatalogPage } = await import('./CustomCatalogPage');
      return <CustomCatalogPage />;
    },
  },
});

export default createFrontendModule({
  pluginId: 'catalog',
  extensions: [customCatalogPage],
});

Inside your custom catalog page component you have full control over the table columns, actions, and options. You can compose a page using components from @backstage/plugin-catalog and @backstage/plugin-catalog-react:

packages/app/src/catalog/CustomCatalogPage.tsx
import {
  PageWithHeader,
  Content,
  ContentHeader,
  SupportButton,
} from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import { CatalogTable } from '@backstage/plugin-catalog';
import {
  EntityListProvider,
  CatalogFilterLayout,
  EntityKindPicker,
  EntityLifecyclePicker,
  EntityNamespacePicker,
  EntityOwnerPicker,
  EntityProcessingStatusPicker,
  EntityTagPicker,
  EntityTypePicker,
  UserListPicker,
} from '@backstage/plugin-catalog-react';

export const CustomCatalogPage = () => {
  const orgName =
    useApi(configApiRef).getOptionalString('organization.name') ?? 'Backstage';

  return (
    <EntityListProvider pagination>
      <PageWithHeader title={orgName} themeId="home">
        <Content>
          <ContentHeader title="">
            <SupportButton>All your software catalog entities</SupportButton>
          </ContentHeader>
          <CatalogFilterLayout>
            <CatalogFilterLayout.Filters>
              <EntityKindPicker />
              <EntityTypePicker />
              <UserListPicker />
              <EntityOwnerPicker />
              <EntityLifecyclePicker />
              <EntityTagPicker />
              <EntityProcessingStatusPicker />
              <EntityNamespacePicker />
            </CatalogFilterLayout.Filters>
            <CatalogFilterLayout.Content>
              <CatalogTable />
            </CatalogFilterLayout.Content>
          </CatalogFilterLayout>
        </Content>
      </PageWithHeader>
    </EntityListProvider>
  );
};
Note

The catalog index page is designed to have a minimal code footprint to support easy customization, but creating a replica does introduce a possibility of drifting out of date over time. Be sure to check the catalog CHANGELOG periodically.

For more details on extension overrides and the different override patterns available, see the extension overrides documentation.

Entity page​

Entity filters​

Many extensions that attach within the catalog entity pages accept a filter configuration. The purpose of the filter configuration is to select what entities the extension should be applied to or be present on. Many of these extension will have a default filter defined, but you can override it by providing your own. When defining filters in code you can use either a predicate function or a entity predicate query, while in configuration you can only use an entity predicate query.

Entity predicate queries​

The entity predicate syntax is a minimal JSON-based query language for filtering catalog entities. It is loosely inspired by the MongoDB query syntax, behaving roughly the same way but with a different set of operators.

The most simple entity predicate is an object expression with key-value mappings where the key is the full dot-separated path to the value in the entity, and the value is the value to do a case insensitive match against. Each entry in this object is evaluated separately, but all of them must match for the overall predicate to result in a match. For example, the following will match any component entities of the type service:

{
  "filter": {
    "kind": "component",
    "spec.type": "service"
  }
}

Or when utilizing YAML syntax:

filter:
  kind: component
  spec.type: service

In addition to this basic syntax, entity predicates support logical operators that can be nested and applied around these object expressions. For example, the following will match all components entities that are of type service or website:

{
  "filter": {
    "$all": [
      {
        "kind": "component"
      },
      {
        "$any": [{ "spec.type": "service" }, { "spec.type": "website" }]
      }
    ]
  }
}

Or when utilizing YAML syntax:

filter:
  $all:
    - kind: component
    - $any:
        - spec.type: service
        - spec.type: website

Finally, entity predicates also support value operators that can be used in place of the values in the object expression. For example, the following is a simpler way to express the previous example:

{
  "filter": {
    "kind": "component",
    "spec.type": { "$in": ["service", "website"] }
  }
}

Or when utilizing YAML syntax:

filter:
  kind: component
  spec.type:
    $in: [service, website]

Entity predicate logical operators​

The following section lists all logical operators for entity predicates.

$all​

The $all operator has the following syntax:

{ $all: [ { <expression1> }, { <expression2> }, ...] }

The $all operator evaluates to true if all expressions within the provided array evaluate to true. This includes an empty array, which means that { "$all": [] } always evaluates to true.

Example usage of $all
filter:
  $all:
    - kind: component
    - $not:
        spec.type: service

$any​

The $any operator has the following syntax:

{ $any: [ { <expression1> }, { <expression2> }, ...] }

The $any operator evaluates to true if at least one of the expressions within the provided array evaluate to true. This includes an empty array, which means that { "$any": [] } always evaluates to false.

Example usage of $any
filter:
  $any:
    - kind: component
    - metadata.annotations.github.com/project-slug: { $exists: true }

$not​

The $not operator has the following syntax:

{ $not: { <expression> } }

The $not operator inverts the result of the provided express. If the expression evaluates to true then $not will evaluate to false, and the other way around.

Example usage of $not
filter:
  $not:
    kind: template

Entity predicate value operators​

The following section lists all value operators for entity predicates.

$exists​

The $exists operator has the following syntax:

{ field: { $exists: <boolean> } }

The $exists operator will evaluate to true if the existence of the value it matches against matches the provided boolean. That is { $exists: true } will evaluate to true if and only if the value is defined, and { $exists: false } will evaluate to true if and only if the value is not defined.

Example usage of $exists
filter:
  metadata.annotations.github.com/project-slug: { $exists: true }

$in​

The $in operator has the following syntax:

{ field: { $in: [ <primitive1>, <primitive2>, ... ] } }

The $in operator will evaluate to true if the value it is matched against is exists within the array of primitives. The comparison is case insensitive and can only be done across primitive values. If the value matched against is an object or array, the operator will always evaluate to false.

Example usage of $in
filter:
  kind:
    $in: [component, api]

$contains​

The $contains operator has the following syntax:

{ field: { $contains: { <expression> } } }

The $contains operator will evaluate to true if the value it is matched against is an array, and at least one of the elements in the array fully matches the provided expression. If the value matched against is not an array, or if the array is empty, the operator will always evaluate to false.

The expression used to match against the array can be any valid entity predicate expression, including logical operators and value operators.

Example usage of $contains
filter:
  relations:
    $contains:
      type: ownedBy
      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.

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).
  • Group icons are only rendered if showNavItemIcons is set to true.

Content ordering within groups​

By default, content items within each group are sorted alphabetically by title. You can change this with the defaultContentOrder option, which supports two modes:

  • title (default) — sort alphabetically by the content extension's title (case-insensitive).
  • natural — preserve the natural extension discovery/registration order.

A page-level defaultContentOrder sets the default for all groups, and individual groups can override it with a per-group contentOrder:

app:
  extensions:
    - page:catalog/entity:
        config:
          # Default content order for all groups
          defaultContentOrder: title

          groups:
            - documentation:
                title: Docs
                # Override: keep natural order for this group
                contentOrder: natural

Note that content ordering only applies to content items within groups. Ungrouped tabs (those not matching any group definition) always retain their natural order.

Group aliases​

Groups can declare aliases — a list of other group IDs that should be treated as equivalent. Any entity content extension targeting an aliased group ID will be included in the aliasing group. This is useful when renaming or merging groups without having to reconfigure individual extensions:

app:
  extensions:
    - page:catalog/entity:
        config:
          groups:
            - develop:
                title: Develop
                # Content targeting 'development' will appear in this group
                aliases:
                  - development

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:

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.

Entity Context Menu​

You can configure the context menu items using EntityContextMenuItemBlueprint. The current items are defined here.

To add a new context item you can do something like this:

import { EntityContextMenuItemBlueprint } from '@backstage/plugin-catalog-react/alpha';
const customEntityMenuItem = EntityContextMenuItemBlueprint.make({
  name: 'open-dialog',
  params: {
    icon: <ExampleIcon />,
    useProps() {
      const dialogApi = useApi(dialogApiRef);
      const { entity } = useEntity();
      return {
        title: 'Open Custom Dialog',
        disabled: false,
        // you can also use href: '/example-path'
        onClick: async () => {
          dialogApi.open(({ dialog }) => (
            <AsyncEntityProvider entity={entity} loading={false}>
              <CustomDialog open onClose={() => dialog.close()} />
            </AsyncEntityProvider>
          ));
        },
      };
    },
  },
});