From 5c76d13ada04af08f68ff2382cef694befcb8889 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustaf=20R=C3=A4ntil=C3=A4?= <g.rantila@gmail.com>
Date: Sat, 7 Feb 2026 18:23:00 +0100
Subject: [PATCH] Allow ref on the Tag component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Gustaf Räntilä <g.rantila@gmail.com>
---
 .changeset/grumpy-signs-deny.md               |  7 ++
 packages/ui/report.api.md                     |  4 +-
 .../ui/src/components/TagGroup/TagGroup.tsx   | 89 ++++++++++---------
 3 files changed, 56 insertions(+), 44 deletions(-)
 create mode 100644 .changeset/grumpy-signs-deny.md

diff --git a/.changeset/grumpy-signs-deny.md b/.changeset/grumpy-signs-deny.md
new file mode 100644
index 0000000000..4654fed83e
--- /dev/null
+++ b/.changeset/grumpy-signs-deny.md
@@ -0,0 +1,7 @@
+---
+'@backstage/ui': patch
+---
+
+Allow `ref` as a prop on the `Tag` component
+
+Affected components: Tag
diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index 82069bc469..5c06b2e953 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1894,7 +1894,9 @@ export const TabsDefinition: {
 export interface TabsProps extends TabsProps_2 {}
 
 // @public
-export const Tag: (props: TagProps) => JSX_2.Element;
+export const Tag: ForwardRefExoticComponent<
+  TagProps & RefAttributes<HTMLDivElement>
+>;
 
 // @public
 export const TagGroup: <T extends object>(
diff --git a/packages/ui/src/components/TagGroup/TagGroup.tsx b/packages/ui/src/components/TagGroup/TagGroup.tsx
index ace4ee24e4..66ef46bb72 100644
--- a/packages/ui/src/components/TagGroup/TagGroup.tsx
+++ b/packages/ui/src/components/TagGroup/TagGroup.tsx
@@ -21,7 +21,7 @@ import {
   Tag as ReactAriaTag,
   Button as ReactAriaButton,
 } from 'react-aria-components';
-import type { ReactNode } from 'react';
+import { forwardRef, type PropsWithRef, type ReactNode, type Ref } from 'react';
 import { RiCloseCircleLine } from '@remixicon/react';
 import clsx from 'clsx';
 import { useStyles } from '../../hooks/useStyles';
@@ -64,47 +64,50 @@ export const TagGroup = <T extends object>(props: TagGroupProps<T>) => {
  *
  * @public
  */
-export const Tag = (props: TagProps) => {
-  const { classNames, cleanedProps } = useStyles(TagGroupDefinition, {
-    size: 'small',
-    ...props,
-  });
-  const { children, className, icon, size, href, ...rest } = cleanedProps;
-  const textValue = typeof children === 'string' ? children : undefined;
+export const Tag = forwardRef(
+  (props: PropsWithRef<TagProps>, ref: Ref<HTMLDivElement>) => {
+    const { classNames, cleanedProps } = useStyles(TagGroupDefinition, {
+      size: 'small',
+      ...props,
+    });
+    const { children, className, icon, size, href, ...rest } = cleanedProps;
+    const textValue = typeof children === 'string' ? children : undefined;
 
-  useRoutingRegistrationEffect(href);
+    useRoutingRegistrationEffect(href);
 
-  return (
-    <ReactAriaTag
-      textValue={textValue}
-      className={clsx(classNames.tag, styles[classNames.tag], className)}
-      data-size={size}
-      href={href}
-      {...rest}
-    >
-      {({ allowsRemoving }) => (
-        <>
-          {icon && (
-            <span
-              className={clsx(classNames.tagIcon, styles[classNames.tagIcon])}
-            >
-              {icon}
-            </span>
-          )}
-          {children as ReactNode}
-          {allowsRemoving && (
-            <ReactAriaButton
-              className={clsx(
-                classNames.tagRemoveButton,
-                styles[classNames.tagRemoveButton],
-              )}
-              slot="remove"
-            >
-              <RiCloseCircleLine size={16} />
-            </ReactAriaButton>
-          )}
-        </>
-      )}
-    </ReactAriaTag>
-  );
-};
+    return (
+      <ReactAriaTag
+        ref={ref}
+        textValue={textValue}
+        className={clsx(classNames.tag, styles[classNames.tag], className)}
+        data-size={size}
+        href={href}
+        {...rest}
+      >
+        {({ allowsRemoving }) => (
+          <>
+            {icon && (
+              <span
+                className={clsx(classNames.tagIcon, styles[classNames.tagIcon])}
+              >
+                {icon}
+              </span>
+            )}
+            {children as ReactNode}
+            {allowsRemoving && (
+              <ReactAriaButton
+                className={clsx(
+                  classNames.tagRemoveButton,
+                  styles[classNames.tagRemoveButton],
+                )}
+                slot="remove"
+              >
+                <RiCloseCircleLine size={16} />
+              </ReactAriaButton>
+            )}
+          </>
+        )}
+      </ReactAriaTag>
+    );
+  },
+);