fix: Tooltip focus issue (#469)

adrienzheng-cb · web-flow · commit 4dff31268371 · 2026-03-09T09:55:11.000-04:00
* fix: Tooltip focus issue

1. Fixed issue when Tooltip loses its focus and disappear immediately when its content has interactive elements.
2. Fixed issue when Tooltip does not announce its content when its anchor is not an iteractive element (eg.div)
3. Added A11y section to docs.

* add new hasInteractiveContent prop

* update changelog
diff --git a/apps/docs/docs/components/overlay/Tooltip/_webExamples.mdx b/apps/docs/docs/components/overlay/Tooltip/_webExamples.mdx
@@ -82,7 +82,7 @@ You can use tooltips within `TextInput` to provide more context.
       <InputLabel htmlFor="tooltip-input-example">Display name</InputLabel>
       {/* Add padding to ensure 24x24 tooltip tap target for a11y compliance */}
       <Tooltip content="This will be visible to other users.">
-        <Icon active color="fg" name="info" padding={0.75} size="xs" tabIndex={0} />
+        <Icon active color="fg" name="info" padding={0.75} size="xs" tabIndex={0} role="button" />
       </Tooltip>
     </HStack>
   }
@@ -111,3 +111,89 @@ function TooltipVisibilityDelay() {
   );
 }
 ```
+
+### Accessibility (A11y)
+
+When tooltip content is non-interactive (text only), focus stays on the trigger and the tooltip is rendered in a portal. When tooltip content has **interactive elements** (links, buttons), set **`hasInteractiveContent={true}`** so the tooltip stays in the document flow and keyboard users can tab into the content. This sets `disablePortal`, `disableAutoFocus`, and `disableFocusTrap` appropriately.
+
+**Tooltip on an icon (or other non-button anchor):**
+
+When using an Icon (or other non-`<button>` element) as the tooltip trigger, add **`role="button"`** and **`tabIndex={0}`** so screen readers (e.g. VoiceOver) can discover it with arrow keys and announce the tooltip. If the icon performs an action on click, use **IconButton** instead so the trigger is a real `<button>`.
+
+**Example: tooltip on an icon (string content)**
+
+```jsx live
+function TooltipIconStringContent() {
+  return (
+    <HStack alignItems="center" gap={2}>
+      <Tooltip content="This will be visible to other users.">
+        <Icon active color="fg" name="info" role="button" tabIndex={0} />
+      </Tooltip>
+      <Text as="span" font="body" color="fgMuted">
+        Focus the icon to hear the tooltip announced.
+      </Text>
+    </HStack>
+  );
+}
+```
+
+**Example: tooltip on an icon (React node content)**
+
+```jsx live
+function TooltipIconReactNodeContent() {
+  return (
+    <HStack alignItems="center" gap={2}>
+      <Tooltip
+        content={
+          <Text font="label2">
+            Styled <strong>description</strong> text.
+          </Text>
+        }
+      >
+        <Icon active color="fg" name="info" role="button" tabIndex={0} />
+      </Tooltip>
+      <Text as="span" font="body" color="fgMuted">
+        Focus the icon to hear the tooltip announced.
+      </Text>
+    </HStack>
+  );
+}
+```
+
+**When tooltip content is interactive (links, buttons):**
+
+- Prefer **Modal** or another pattern for actionable content when possible. Tooltips are intended for short, non-interactive descriptions.
+- If you must use interactive content inside a tooltip, set **`hasInteractiveContent={true}`** so the content stays in the document flow. The prop allows keyboard users to tab into the tooltip, through its content, and out to the next focusable element on the page. With the default portal, focus behavior can be inconsistent when moving between trigger and content.
+
+**Example: tooltip with interactive content**
+
+```jsx live
+function TooltipWithInteractiveContent() {
+  return (
+    <Box position="relative" paddingY={5}>
+      <Text as="span" font="body" color="fgMuted">
+        Set your default display currency.{' '}
+      </Text>
+      <Tooltip
+        content={
+          <Text font="label2" color="fg">
+            Learn more at{' '}
+            <Text
+              as="a"
+              href="https://www.coinbase.com/settings"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              Settings
+            </Text>
+            .
+          </Text>
+        }
+        hasInteractiveContent
+      >
+        <Icon active color="fg" name="info" paddingStart={1} role="button" tabIndex={0} />
+      </Tooltip>
+    </Box>
+  );
+}
+```
diff --git a/apps/docs/src/theme/Navbar/MobileSidebar/index.tsx b/apps/docs/src/theme/Navbar/MobileSidebar/index.tsx
@@ -20,7 +20,9 @@ export default function NavbarMobileSidebar(): JSX.Element | null {
   }, []);
 
   const handleEscPress = useCallback(() => {
-    mobileSidebar.toggle();
+    if (mobileSidebar.shown) {
+      mobileSidebar.toggle();
+    }
   }, [mobileSidebar]);
 
   // Set aria-hidden on main content when sidebar is open
diff --git a/packages/common/CHANGELOG.md b/packages/common/CHANGELOG.md
@@ -8,6 +8,10 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.51.0 ((3/9/2026, 06:39 AM PST))
+
+This is an artificial version bump with no new change.
+
 ## 8.50.0 ((3/6/2026, 09:36 AM PST))
 
 This is an artificial version bump with no new change.
diff --git a/packages/common/package.json b/packages/common/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-common",
-  "version": "8.50.0",
+  "version": "8.51.0",
   "description": "Coinbase Design System - Common",
   "repository": {
     "type": "git",
diff --git a/packages/mcp-server/CHANGELOG.md b/packages/mcp-server/CHANGELOG.md
@@ -8,6 +8,10 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.51.0 ((3/9/2026, 06:39 AM PST))
+
+This is an artificial version bump with no new change.
+
 ## 8.50.0 ((3/6/2026, 09:36 AM PST))
 
 This is an artificial version bump with no new change.
diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-mcp-server",
-  "version": "8.50.0",
+  "version": "8.51.0",
   "description": "Coinbase Design System - MCP Server",
   "repository": {
     "type": "git",
diff --git a/packages/mobile/CHANGELOG.md b/packages/mobile/CHANGELOG.md
@@ -8,6 +8,10 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.51.0 ((3/9/2026, 06:39 AM PST))
+
+This is an artificial version bump with no new change.
+
 ## 8.50.0 (3/6/2026 PST)
 
 #### 🚀 Updates
diff --git a/packages/mobile/package.json b/packages/mobile/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-mobile",
-  "version": "8.50.0",
+  "version": "8.51.0",
   "description": "Coinbase Design System - Mobile",
   "repository": {
     "type": "git",
diff --git a/packages/web/CHANGELOG.md b/packages/web/CHANGELOG.md
@@ -8,6 +8,16 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.51.0 (3/9/2026 PST)
+
+#### 🚀 Updates
+
+- Added hasInteractiveContent prop to Tooltip to correctly handle keyboard navigation when content includes interactive elements. [[#469](https://github.com/coinbase/cds/pull/469)] [DX-5097]
+
+#### 🐞 Fixes
+
+- Fixed issue when tooltip does not announce its content when content is a React Node instead of a string. [[#469](https://github.com/coinbase/cds/pull/469)]
+
 ## 8.50.0 (3/6/2026 PST)
 
 #### 🚀 Updates
diff --git a/packages/web/package.json b/packages/web/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-web",
-  "version": "8.50.0",
+  "version": "8.51.0",
   "description": "Coinbase Design System - Web",
   "repository": {
     "type": "git",
diff --git a/packages/web/src/overlays/__stories__/Tooltip.stories.tsx b/packages/web/src/overlays/__stories__/Tooltip.stories.tsx
@@ -8,6 +8,7 @@ import type {
 import { Button } from '../../buttons/Button';
 import { IconButton } from '../../buttons/IconButton';
 import { DotSymbol } from '../../dots/DotSymbol';
+import { Icon } from '../../icons/Icon';
 import { HStack } from '../../layout/HStack';
 import { VStack } from '../../layout/VStack';
 import { Text } from '../../typography/Text';
@@ -81,6 +82,7 @@ const BasicTooltip = ({ content, openDelay, closeDelay }: BasicTooltipProps) =>
 
         <VStack gap={3} paddingX={2}>
           <Tooltip
+            hasInteractiveContent
             closeDelay={closeDelay}
             content={
               <VStack gap={2}>
@@ -314,3 +316,64 @@ DelayedVisibility.args = {
   openDelay: 400,
   closeDelay: 150,
 };
+
+export const TooltipOnIcon = () => (
+  <PortalProvider>
+    <HStack alignItems="center" gap={2}>
+      <Tooltip content="This will be visible to other users.">
+        <Icon active color="fg" name="info" role="button" tabIndex={0} />
+      </Tooltip>
+      <Text as="span" color="fgMuted" font="body">
+        Focus the icon to hear the tooltip announced.
+      </Text>
+    </HStack>
+  </PortalProvider>
+);
+
+export const TooltipOnIconReactNode = () => (
+  <PortalProvider>
+    <HStack alignItems="center" gap={2}>
+      <Tooltip
+        content={
+          <Text font="label2">
+            Styled <strong>description</strong> text.
+          </Text>
+        }
+      >
+        <Icon active color="fg" name="info" role="button" tabIndex={0} />
+      </Tooltip>
+      <Text as="span" color="fgMuted" font="body">
+        Focus the icon to hear the tooltip announced.
+      </Text>
+    </HStack>
+  </PortalProvider>
+);
+
+export const TooltipWithInteractiveContent = () => (
+  <PortalProvider>
+    <HStack alignItems="center" gap={2}>
+      <Tooltip
+        hasInteractiveContent
+        content={
+          <Text color="fg" font="label2">
+            Learn more at{' '}
+            <Text
+              as="a"
+              href="https://www.coinbase.com/settings"
+              rel="noopener noreferrer"
+              target="_blank"
+            >
+              Settings
+            </Text>
+            .
+          </Text>
+        }
+      >
+        <Icon active color="fg" name="info" paddingStart={1} role="button" tabIndex={0} />
+      </Tooltip>
+      <Text as="span" color="fgMuted" font="body">
+        Set your default display currency.{' '}
+      </Text>
+    </HStack>
+  </PortalProvider>
+);
diff --git a/packages/web/src/overlays/popover/Popover.tsx b/packages/web/src/overlays/popover/Popover.tsx
@@ -119,17 +119,17 @@ export const Popover = memo(
         popperStyles.popper,
         popperAttributes.popper,
         handleCaptureEvents,
-        handleClose,
-        testID,
-        content,
-        controlledElementAccessibilityProps,
-        disableFocusTrap,
+        autoFocusDelay,
         disableAutoFocus,
+        disableFocusTrap,
         disableTypeFocus,
         focusTabIndexElements,
+        handleClose,
         respectNegativeTabIndex,
-        autoFocusDelay,
         restoreFocusOnUnmount,
+        testID,
+        controlledElementAccessibilityProps,
+        content,
       ],
     );
 
@@ -154,13 +154,13 @@ export const Popover = memo(
     return (
       <div
         className={block ? blockCss : undefined}
+        onBlur={onBlur}
         onMouseEnter={disabled ? undefined : onMouseEnter}
         onMouseLeave={disabled ? undefined : onMouseLeave}
       >
         <div
           ref={setSubject}
           className={cx(subjectCss, block && blockCss)}
-          onBlur={onBlur}
           onClick={disabled ? undefined : onPressSubject}
           onFocus={disabled ? undefined : onFocus}
           onMouseDown={disabled ? undefined : onMouseDown}
diff --git a/packages/web/src/overlays/tooltip/Tooltip.tsx b/packages/web/src/overlays/tooltip/Tooltip.tsx
@@ -17,14 +17,15 @@ export const Tooltip = ({
   elevation,
   placement = 'top',
   gap = 1,
-  disablePortal,
   testID,
   zIndex,
   tooltipId: tooltipIdDefault,
   visible,
+  hasInteractiveContent,
   invertColorScheme = true,
-  disableFocusTrap,
-  disableAutoFocus,
+  disableAutoFocus = hasInteractiveContent,
+  disableFocusTrap = hasInteractiveContent,
+  disablePortal = hasInteractiveContent,
   disableTypeFocus,
   focusTabIndexElements,
   respectNegativeTabIndex,
@@ -49,10 +50,17 @@ export const Tooltip = ({
   );
 
   const clonedChild = useMemo(() => {
-    return cloneElement(children, {
-      'aria-describedby': tooltipId,
-    });
-  }, [children, tooltipId]);
+    const isStringContent = typeof content === 'string';
+    return cloneElement(
+      children,
+      // String content: Use only aria-label so the trigger is announced on focus without
+      // double announcement (aria-describedby would point to the same text when the tooltip is open).
+      // Non-string content: Use only aria-describedby to associate the visible tooltip (id=tooltipId).
+      // We cannot use aria-label here (it accepts only strings). May not announce on focus for
+      // non-button triggers due to timing (describedby target mounts when tooltip opens).
+      isStringContent ? { 'aria-label': content } : { 'aria-describedby': tooltipId },
+    );
+  }, [children, content, tooltipId]);
 
   const contentPosition = useMemo(
     () => ({
@@ -63,6 +71,18 @@ export const Tooltip = ({
 
   const isVisible = useMemo(() => visible !== false && isOpen, [visible, isOpen]);
 
+  const handleBlur = useCallback(
+    (event?: React.FocusEvent) => {
+      const relatedTarget = event?.relatedTarget as Node | null;
+      const currentTarget = event?.currentTarget as Node | null;
+      if (relatedTarget && currentTarget?.contains(relatedTarget)) {
+        return;
+      }
+      handleOnBlur();
+    },
+    [handleOnBlur],
+  );
+
   return (
     <Popover
       autoFocusDelay={autoFocusDelay}
@@ -85,7 +105,7 @@ export const Tooltip = ({
       disableTypeFocus={disableTypeFocus}
       focusTabIndexElements={focusTabIndexElements}
       invertColorScheme={invertColorScheme}
-      onBlur={handleOnBlur}
+      onBlur={handleBlur}
       onFocus={handleOnFocus}
       onMouseDown={preventMouseDown}
       onMouseEnter={handleMouseEnter}
diff --git a/packages/web/src/overlays/tooltip/TooltipProps.ts b/packages/web/src/overlays/tooltip/TooltipProps.ts
@@ -60,6 +60,10 @@ export type TooltipBaseProps = SharedProps &
      * A unique ID used to ensure tooltips are accessible
      */
     tooltipId?: string;
+    /**
+     * Whether the tooltip has interactive elements inside the content.
+     */
+    hasInteractiveContent?: boolean;
   };
 
 export type TooltipProps = TooltipBaseProps;

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@coinbase/cds-common",`
`3`		`- "version": "8.50.0",`
	`3`	`+ "version": "8.51.0",`
`4`	`4`	`"description": "Coinbase Design System - Common",`
`5`	`5`	`"repository": {`
`6`	`6`	`"type": "git",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@coinbase/cds-mcp-server",`
`3`		`- "version": "8.50.0",`
	`3`	`+ "version": "8.51.0",`
`4`	`4`	`"description": "Coinbase Design System - MCP Server",`
`5`	`5`	`"repository": {`
`6`	`6`	`"type": "git",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@coinbase/cds-mobile",`
`3`		`- "version": "8.50.0",`
	`3`	`+ "version": "8.51.0",`
`4`	`4`	`"description": "Coinbase Design System - Mobile",`
`5`	`5`	`"repository": {`
`6`	`6`	`"type": "git",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@coinbase/cds-web",`
`3`		`- "version": "8.50.0",`
	`3`	`+ "version": "8.51.0",`
`4`	`4`	`"description": "Coinbase Design System - Web",`
`5`	`5`	`"repository": {`
`6`	`6`	`"type": "git",`