Replace deprecated humanizeEntityRef with Catalog Presentation API

Migrate all humanizeEntityRef and humanizeEntity usages to the Catalog Presentation API across catalog, catalog-react, org-react, catalog-import, scaffolder, and techdocs plugins. - Use useEntityPresentation hook in React component contexts (AncestryPage) - Use defaultEntityPresentation for non-React contexts like sort comparators, filter functions, and data mappers - Add @deprecated tags to humanizeEntityRef and humanizeEntity - Improve TSDoc on entityPresentationApiRef, EntityPresentationApi, useEntityPresentation, EntityDisplayName, and defaultEntityPresentation with guidance on which to use when - Add Entity Presentation docs page with usage examples and migration guide Made-with: Cursor Signed-off-by: Marat Dyatko <maratd@spotify.com>
2026-03-25 16:15:27 +01:00
parent 36d205a455
commit 5f9a531412
24 changed files with 275 additions and 69 deletions
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-import': patch
+---
+
+Replaced `humanizeEntityRef` with `defaultEntityPresentation` from the Catalog Presentation API in `StepPrepareCreatePullRequest`.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-react': patch
+---
+
+Replaced `humanizeEntityRef` with `defaultEntityPresentation` and `useEntityPresentation` from the Catalog Presentation API in `EntityOwnerPicker`, `EntityTable`, `EntityDataTable`, and `AncestryPage` components.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+Replaced `humanizeEntityRef` with `defaultEntityPresentation` from the Catalog Presentation API in `CatalogTable` and its column factories.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-org-react': patch
+---
+
+Replaced `humanizeEntityRef` with `defaultEntityPresentation` from the Catalog Presentation API in `GroupListPicker`.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': patch
+---
+
+Replaced `humanizeEntityRef` with `defaultEntityPresentation` from the Catalog Presentation API in `TemplateFormPreviewer`.
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs': patch
+---
+
+Replaced `humanizeEntityRef` with `defaultEntityPresentation` from the Catalog Presentation API in TechDocs table helpers.
@@ -0,0 +1,117 @@
+---
+id: entity-presentation
+title: Entity Presentation
+description: How to display entity names and control how entities are represented in the Backstage interface
+---
+
+The _Entity Presentation API_ controls how catalog entities are displayed
+throughout the Backstage interface. Instead of rendering raw entity refs like
+`component:default/my-service`, the API resolves a human-friendly display
+name from fields such as `metadata.title` and `spec.profile.displayName`.
+
+## Displaying entity names
+
+There are three ways to display entity names, depending on context:
+
+### `EntityDisplayName` component
+
+The simplest option for React components. Renders a styled entity name with
+an optional icon and tooltip:
+
+```tsx
+import { EntityDisplayName } from '@backstage/plugin-catalog-react';
+
+<EntityDisplayName entityRef="component:default/my-service" />;
+```
+
+You can pass an entity ref string, an `Entity` object, or a
+`CompoundEntityRef`. The component supports optional `hideIcon` and
+`disableTooltip` props.
+
+### `useEntityPresentation` hook
+
+Use this hook when you need access to the raw presentation data in a React
+component, for example to render the title in a custom layout:
+
+```tsx
+import { useEntityPresentation } from '@backstage/plugin-catalog-react';
+
+function MyComponent({ entityRef }: { entityRef: string }) {
+  const { primaryTitle, secondaryTitle, Icon } =
+    useEntityPresentation(entityRef);
+
+  return (
+    <span>
+      {Icon && <Icon fontSize="inherit" />}
+      {primaryTitle}
+    </span>
+  );
+}
+```
+
+The hook subscribes to the `EntityPresentationApi` and returns a snapshot
+that may update over time as additional data is fetched in the background.
+If no presentation API is registered, it falls back to
+`defaultEntityPresentation`.
+
+### `defaultEntityPresentation` function
+
+A synchronous helper for non-React contexts where hooks are not available.
+Use it in sort comparators, filter functions, table column factories, and
+data mappers:
+
+```ts
+import { defaultEntityPresentation } from '@backstage/plugin-catalog-react';
+
+const title = defaultEntityPresentation(entity, {
+  defaultKind: 'Component',
+}).primaryTitle;
+```
+
+This resolves `primaryTitle` as the first available value among
+`spec.profile.displayName`, `metadata.title`, and a shortened entity ref.
+
+## Customizing entity presentation
+
+To customize how entities are rendered, provide your own implementation of
+the `EntityPresentationApi` interface and register it with the app's API
+factory:
+
+```ts
+import {
+  entityPresentationApiRef,
+  type EntityPresentationApi,
+} from '@backstage/plugin-catalog-react';
+import { createApiFactory } from '@backstage/core-plugin-api';
+
+const myPresentationApi: EntityPresentationApi = {
+  forEntity(entityOrRef, context) {
+    // Return an EntityRefPresentation with snapshot, update$, and promise
+  },
+};
+
+createApiFactory({
+  api: entityPresentationApiRef,
+  deps: {},
+  factory: () => myPresentationApi,
+});
+```
+
+The presentation snapshot includes `primaryTitle`, an optional
+`secondaryTitle` for tooltips, and an optional `Icon` component. You can
+also emit updated snapshots over time via the `update$` observable.
+
+## Migrating from `humanizeEntityRef`
+
+The `humanizeEntityRef` and `humanizeEntity` functions are deprecated. They
+only produce a shortened entity ref string and do not resolve display names
+from `metadata.title` or `spec.profile.displayName`.
+
+Replace them as follows:
+
+| Old code                                                            | Replacement                                                       |
+| :------------------------------------------------------------------ | :---------------------------------------------------------------- |
+| `humanizeEntityRef(entity)` in JSX                                  | `<EntityDisplayName entityRef={entity} />`                        |
+| `humanizeEntityRef(entity)` in a hook-accessible context            | `useEntityPresentation(entity).primaryTitle`                      |
+| `humanizeEntityRef(entity, { defaultKind })` in a sort/filter/label | `defaultEntityPresentation(entity, { defaultKind }).primaryTitle` |
+| `humanizeEntity(entity, fallback)`                                  | `defaultEntityPresentation(entity).primaryTitle`                  |
@@ -62,6 +62,7 @@ nav:
          - Extending the model: 'features/software-catalog/extending-the-model.md'
          - External integrations: 'features/software-catalog/external-integrations.md'
          - Catalog Customization: 'features/software-catalog/catalog-customization.md'
+          - Entity Presentation: 'features/software-catalog/entity-presentation.md'
          - API: 'features/software-catalog/api.md'
          - FAQ: 'features/software-catalog/faq.md'
      - Kubernetes:
@@ -20,7 +20,7 @@ import { assertError } from '@backstage/errors';
 import { useTranslationRef } from '@backstage/frontend-plugin-api';
 import {
  catalogApiRef,
-  humanizeEntityRef,
+  defaultEntityPresentation,
 } from '@backstage/plugin-catalog-react';
 import Box from '@material-ui/core/Box';
 import FormHelperText from '@material-ui/core/FormHelperText';
@@ -162,7 +162,10 @@ export const StepPrepareCreatePullRequest = (
    });

    return groupEntities.items
-      .map(e => humanizeEntityRef(e, { defaultKind: 'group' }))
+      .map(
+        e =>
+          defaultEntityPresentation(e, { defaultKind: 'group' }).primaryTitle,
+      )
      .sort();
  });

@@ -834,7 +834,7 @@ export function getEntitySourceLocation(
  scmIntegrationsApi: typeof scmIntegrationsApiRef.T,
 ): EntitySourceLocation | undefined;

-// @public (undocumented)
+// @public @deprecated (undocumented)
 export function humanizeEntityRef(
  entityRef: Entity | CompoundEntityRef,
  opts?: {
@@ -25,6 +25,21 @@ import { Observable } from '@backstage/types';
 /**
 * An API that handles how to represent entities in the interface.
 *
+ * @remarks
+ *
+ * There are several ways to consume this API depending on context:
+ *
+ * - In React components, use the {@link useEntityPresentation} hook to get a
+ *   reactive presentation snapshot that updates over time.
+ *
+ * - For simple inline rendering, use the {@link EntityDisplayName} component
+ *   which wraps the hook and renders a styled entity name with optional icon
+ *   and tooltip.
+ *
+ * - In non-React contexts such as sort comparators, filter functions, or data
+ *   mappers, use the {@link defaultEntityPresentation} function which
+ *   synchronously extracts a display name from an already-loaded entity.
+ *
 * @public
 */
 export const entityPresentationApiRef: ApiRef<EntityPresentationApi> =
@@ -120,8 +135,19 @@ export interface EntityRefPresentation {
 *
 * @remarks
 *
- * Most consumers will want to use the {@link useEntityPresentation} hook
- * instead of this interface directly.
+ * Most consumers will not need to interact with this interface directly.
+ * Instead, use one of the following:
+ *
+ * - {@link useEntityPresentation} — React hook for reactive presentation data.
+ *
+ * - {@link EntityDisplayName} — React component that renders an entity name
+ *   with optional icon and tooltip.
+ *
+ * - {@link defaultEntityPresentation} — synchronous helper for non-React
+ *   contexts where you already have the entity object.
+ *
+ * Implement this interface to customize how entities are displayed throughout
+ * the Backstage interface.
 *
 * @public
 */
@@ -24,7 +24,20 @@ import get from 'lodash/get';
 import { EntityRefPresentationSnapshot } from './EntityPresentationApi';

 /**
- * This returns the default representation of an entity.
+ * Returns the default representation of an entity.
+ *
+ * @remarks
+ *
+ * This is a synchronous helper that extracts a display name from an
+ * already-loaded entity or entity ref. It resolves `primaryTitle` as the
+ * first available value among `spec.profile.displayName`, `metadata.title`,
+ * and a shortened entity ref string.
+ *
+ * Use this in non-React contexts where hooks are not available, such as sort
+ * comparators, filter functions, table column factories, and data mappers.
+ * In React components, prefer the {@link useEntityPresentation} hook or the
+ * {@link EntityDisplayName} component, which support async enrichment via
+ * the {@link EntityPresentationApi}.
 *
 * @public
 * @param entityOrRef - Either an entity, or a ref to it.
@@ -32,6 +32,19 @@ import { useUpdatingObservable } from './useUpdatingObservable';
 /**
 * Returns information about how to represent an entity in the interface.
 *
+ * @remarks
+ *
+ * This hook subscribes to the {@link EntityPresentationApi} and returns a
+ * snapshot that may update over time as richer data is fetched (for example,
+ * resolving `metadata.title` from a string entity ref). If no presentation
+ * API is registered, it falls back to {@link defaultEntityPresentation}.
+ *
+ * For simple inline rendering, consider using the {@link EntityDisplayName}
+ * component instead, which wraps this hook with icon and tooltip support.
+ *
+ * For non-React contexts such as sort comparators or data mappers, use
+ * {@link defaultEntityPresentation} directly.
+ *
 * @public
 * @param entityOrRef - The entity to represent, or an entity ref to it. If you
 *   pass in an entity, it is assumed that it is NOT a partial one - i.e. only
@@ -20,11 +20,8 @@ import {
  RELATION_PART_OF,
 } from '@backstage/catalog-model';
 import { Cell, CellText, Column, ColumnConfig, TableItem } from '@backstage/ui';
-import {
-  EntityRefLink,
-  EntityRefLinks,
-  humanizeEntityRef,
-} from '../EntityRefLink';
+import { EntityRefLink, EntityRefLinks } from '../EntityRefLink';
+import { defaultEntityPresentation } from '../../apis';
 import { EntityTableColumnTitle } from '../EntityTable/TitleColumn';
 import { getEntityRelations } from '../../utils';

@@ -63,8 +60,8 @@ export const columnFactories = Object.freeze({
        </Cell>
      ),
      sortValue: entity =>
-        entity.metadata?.title ||
-        humanizeEntityRef(entity, { defaultKind: options.defaultKind }),
+        defaultEntityPresentation(entity, { defaultKind: options.defaultKind })
+          .primaryTitle,
    };
  },

@@ -98,7 +95,12 @@ export const columnFactories = Object.freeze({
      ),
      sortValue: entity =>
        getEntityRelations(entity, options.relation, options.filter)
-          .map(r => humanizeEntityRef(r, { defaultKind: options.defaultKind }))
+          .map(
+            r =>
+              defaultEntityPresentation(r, {
+                defaultKind: options.defaultKind,
+              }).primaryTitle,
+          )
          .join(', '),
    };
  },
@@ -62,6 +62,16 @@ export type EntityDisplayNameProps = {
 /**
 * Shows a nice representation of a reference to an entity.
 *
+ * @remarks
+ *
+ * This component uses the {@link useEntityPresentation} hook internally and
+ * renders the entity's primary title with optional icon and tooltip. It is
+ * the simplest way to display an entity name in JSX.
+ *
+ * For more control over the presentation data, use the
+ * {@link useEntityPresentation} hook directly. For non-React contexts, use
+ * {@link defaultEntityPresentation}.
+ *
 * @public
 */
 export const EntityDisplayName = (
@@ -33,7 +33,7 @@ import { EntityOwnerFilter } from '../../filters';
 import { useDebouncedEffect } from '@react-hookz/web';
 import PersonIcon from '@material-ui/icons/Person';
 import GroupIcon from '@material-ui/icons/Group';
-import { humanizeEntity, humanizeEntityRef } from '../EntityRefLink/humanize';
+import { defaultEntityPresentation } from '../../apis';
 import { useFetchEntities } from './useFetchEntities';
 import { withStyles } from '@material-ui/core/styles';
 import { useEntityPresentation } from '../../apis';
@@ -203,7 +203,7 @@ export const EntityOwnerPicker = (props?: EntityOwnerPickerProps) => {
                  defaultNamespace: 'default',
                })
              : o;
-          return humanizeEntity(entity, humanizeEntityRef(entity));
+          return defaultEntityPresentation(entity).primaryTitle;
        }}
        onChange={(_: object, owners) => {
          setText('');
@@ -25,6 +25,11 @@ import get from 'lodash/get';
 * @param defaultNamespace - if set to false then namespace is never omitted,
 * if set to string which matches namespace of entity then omitted
 *
+ * @deprecated Use {@link defaultEntityPresentation} for non-React contexts,
+ * or {@link useEntityPresentation} / {@link EntityDisplayName} in React
+ * components. These provide richer display names using `metadata.title` and
+ * `spec.profile.displayName` in addition to the entity ref.
+ *
 * @public
 **/
 export function humanizeEntityRef(
@@ -76,6 +81,9 @@ export function humanizeEntityRef(
 *
 * If neither of those are found or populated, fallback to `defaultName`.
 *
+ * @deprecated Use {@link defaultEntityPresentation} instead, which provides
+ * the same resolution logic via `primaryTitle`.
+ *
 * @param entity - Entity to convert.
 * @param defaultName - If entity readable name is not available, `defaultName` will be returned.
 * @returns Readable name, defaults to `defaultName`.
@@ -22,11 +22,8 @@ import {
 } from '@backstage/catalog-model';
 import { OverflowTooltip, TableColumn } from '@backstage/core-components';
 import { getEntityRelations } from '../../utils';
-import {
-  EntityRefLink,
-  EntityRefLinks,
-  humanizeEntityRef,
-} from '../EntityRefLink';
+import { EntityRefLink, EntityRefLinks } from '../EntityRefLink';
+import { defaultEntityPresentation } from '../../apis';
 import { EntityTableColumnTitle } from './TitleColumn';

 /** @public */
@@ -36,12 +33,7 @@ export const columnFactories = Object.freeze({
  }): TableColumn<T> {
    const { defaultKind } = options;
    function formatContent(entity: T): string {
-      return (
-        entity.metadata?.title ||
-        humanizeEntityRef(entity, {
-          defaultKind,
-        })
-      );
+      return defaultEntityPresentation(entity, { defaultKind }).primaryTitle;
    }

    return {
@@ -84,7 +76,7 @@ export const columnFactories = Object.freeze({

    function formatContent(entity: T): string {
      return getRelations(entity)
-        .map(r => humanizeEntityRef(r, { defaultKind }))
+        .map(r => defaultEntityPresentation(r, { defaultKind }).primaryTitle)
        .join(', ');
    }

@@ -35,8 +35,8 @@ import { useLayoutEffect, useRef, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import useAsync from 'react-use/esm/useAsync';
 import { catalogApiRef } from '../../../api';
-import { humanizeEntityRef } from '../../EntityRefLink';
 import { entityRouteRef } from '../../../routes';
+import { useEntityPresentation } from '../../../apis';
 import { EntityKindIcon } from './EntityKindIcon';
 import { catalogReactTranslationRef } from '../../../translation';
 import { useTranslationRef } from '@backstage/core-plugin-api/alpha';
@@ -137,15 +137,7 @@ function CustomNode({ node }: DependencyGraphTypes.RenderNodeProps<NodeType>) {
  const paddedWidth = paddedIconWidth + width + padding * 2;
  const paddedHeight = height + padding * 2;

-  const displayTitle =
-    node.metadata.title ||
-    (node.kind && node.metadata.name && node.metadata.namespace
-      ? humanizeEntityRef({
-          kind: node.kind,
-          name: node.metadata.name,
-          namespace: node.metadata.namespace || '',
-        })
-      : node.id);
+  const { primaryTitle: displayTitle } = useEntityPresentation(node);

  const onClick = () => {
    navigate(
@@ -29,8 +29,8 @@ import {
  WarningPanel,
 } from '@backstage/core-components';
 import {
+  defaultEntityPresentation,
  getEntityRelations,
-  humanizeEntityRef,
  useEntityList,
  useStarredEntities,
 } from '@backstage/plugin-catalog-react';
@@ -71,10 +71,8 @@ export interface CatalogTableProps {

 const refCompare = (a: Entity, b: Entity) => {
  const toRef = (entity: Entity) =>
-    entity.metadata.title ||
-    humanizeEntityRef(entity, {
-      defaultKind: 'Component',
-    });
+    defaultEntityPresentation(entity, { defaultKind: 'Component' })
+      .primaryTitle;

  return toRef(a).localeCompare(toRef(b));
 };
@@ -292,19 +290,21 @@ function toEntityRow(entity: Entity) {
      // This name is here for backwards compatibility mostly; the
      // presentation of refs in the table should in general be handled with
      // EntityRefLink / EntityName components
-      name: humanizeEntityRef(entity, {
-        defaultKind: 'Component',
-      }),
+      name: defaultEntityPresentation(entity, { defaultKind: 'Component' })
+        .primaryTitle,
      entityRef: stringifyEntityRef(entity),
      ownedByRelationsTitle: ownedByRelations
-        .map(r => humanizeEntityRef(r, { defaultKind: 'group' }))
+        .map(
+          r =>
+            defaultEntityPresentation(r, { defaultKind: 'group' }).primaryTitle,
+        )
        .join(', '),
      ownedByRelations,
      partOfSystemRelationTitle: partOfSystemRelations
-        .map(r =>
-          humanizeEntityRef(r, {
-            defaultKind: 'system',
-          }),
+        .map(
+          r =>
+            defaultEntityPresentation(r, { defaultKind: 'system' })
+              .primaryTitle,
        )
        .join(', '),
      partOfSystemRelations,
@@ -14,7 +14,7 @@
 * limitations under the License.
 */
 import {
-  humanizeEntityRef,
+  defaultEntityPresentation,
  EntityRefLink,
  EntityRefLinks,
 } from '@backstage/plugin-catalog-react';
@@ -33,12 +33,9 @@ export const columnFactories = Object.freeze({
    defaultKind?: string;
  }): TableColumn<CatalogTableRow> {
    function formatContent(entity: Entity): string {
-      return (
-        entity.metadata?.title ||
-        humanizeEntityRef(entity, {
-          defaultKind: options?.defaultKind,
-        })
-      );
+      return defaultEntityPresentation(entity, {
+        defaultKind: options?.defaultKind,
+      }).primaryTitle;
    }

    return {
@@ -17,7 +17,7 @@
 import { MouseEvent, useState, useCallback } from 'react';
 import {
  catalogApiRef,
-  humanizeEntityRef,
+  defaultEntityPresentation,
 } from '@backstage/plugin-catalog-react';
 import TextField from '@material-ui/core/TextField';
 import Autocomplete from '@material-ui/lab/Autocomplete';
@@ -25,7 +25,7 @@ import useAsync from 'react-use/esm/useAsync';
 import Popover from '@material-ui/core/Popover';
 import { useApi } from '@backstage/core-plugin-api';
 import { ResponseErrorPanel } from '@backstage/core-components';
-import { Entity, GroupEntity } from '@backstage/catalog-model';
+import { GroupEntity } from '@backstage/catalog-model';
 import { GroupListPickerButton } from './GroupListPickerButton';

 /**
@@ -85,8 +85,6 @@ export const GroupListPicker = (props: GroupListPickerProps) => {
    return <ResponseErrorPanel error={error} />;
  }

-  const getHumanEntityRef = (entity: Entity) => humanizeEntityRef(entity);
-
  return (
    <>
      <Popover
@@ -101,7 +99,7 @@ export const GroupListPicker = (props: GroupListPickerProps) => {
          options={groups ?? []}
          groupBy={option => option.spec.type}
          getOptionLabel={option =>
-            option.spec.profile?.displayName ?? getHumanEntityRef(option)
+            defaultEntityPresentation(option).primaryTitle
          }
          inputValue={inputValue}
          onInputChange={(_, value) => setInputValue(value)}
@@ -24,7 +24,7 @@ import { makeStyles } from '@material-ui/core/styles';
 import { alertApiRef, useApi, useRouteRef } from '@backstage/core-plugin-api';
 import {
  catalogApiRef,
-  humanizeEntityRef,
+  defaultEntityPresentation,
 } from '@backstage/plugin-catalog-react';
 import {
  LayoutOptions,
@@ -169,9 +169,9 @@ export const TemplateFormPreviewer = ({
        .then(({ items }) =>
          setTemplateOptions(
            items.map(template => ({
-              label:
-                template.metadata.title ??
-                humanizeEntityRef(template, { defaultKind: 'template' }),
+              label: defaultEntityPresentation(template, {
+                defaultKind: 'template',
+              }).primaryTitle,
              value: template,
            })),
          ),
@@ -16,8 +16,8 @@

 import { RELATION_OWNED_BY, Entity } from '@backstage/catalog-model';
 import {
+  defaultEntityPresentation,
  getEntityRelations,
-  humanizeEntityRef,
 } from '@backstage/plugin-catalog-react';
 import { toLowerMaybe } from '../../../helpers';
 import { ConfigApi, RouteFunc } from '@backstage/core-plugin-api';
@@ -48,7 +48,11 @@ export function entitiesToDocsMapper(
        }),
        ownedByRelations,
        ownedByRelationsTitle: ownedByRelations
-          .map(r => humanizeEntityRef(r, { defaultKind: 'group' }))
+          .map(
+            r =>
+              defaultEntityPresentation(r, { defaultKind: 'group' })
+                .primaryTitle,
+          )
          .join(', '),
      },
    };