coder · aqandrew · Nov 25, 2025 · Nov 20, 2025 · Nov 20, 2025 · Nov 20, 2025
diff --git a/site/src/components/Badges/Badges.tsx b/site/src/components/Badges/Badges.tsx
@@ -1,6 +1,10 @@
 import type { Interpolation, Theme } from "@emotion/react";
-import Tooltip from "@mui/material/Tooltip";
 import { Stack } from "components/Stack/Stack";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "components/Tooltip/Tooltip";
 import {
 	type FC,
 	forwardRef,
@@ -69,16 +73,26 @@ export const NotHealthyBadge: FC = () => {
 
 export const NotRegisteredBadge: FC = () => {
 	return (
-		<Tooltip title="Workspace Proxy has never come online and needs to be started.">
-			<span css={[styles.badge, styles.warnBadge]}>Never seen</span>
+		<Tooltip>
+			<TooltipTrigger asChild>
+				<span css={[styles.badge, styles.warnBadge]}>Never seen</span>
+			</TooltipTrigger>
+			<TooltipContent side="bottom" className="max-w-xs">
+				Workspace Proxy has never come online and needs to be started.
+			</TooltipContent>
 		</Tooltip>
 	);
 };
 
 export const NotReachableBadge: FC = () => {
 	return (
-		<Tooltip title="Workspace Proxy not responding to http(s) requests.">
-			<span css={[styles.badge, styles.warnBadge]}>Not reachable</span>
+		<Tooltip>
+			<TooltipTrigger asChild>
+				<span css={[styles.badge, styles.warnBadge]}>Not reachable</span>
+			</TooltipTrigger>
+			<TooltipContent side="bottom" className="max-w-xs">
+				Workspace Proxy not responding to http(s) requests.
+			</TooltipContent>
 		</Tooltip>
 	);
 };

diff --git a/site/src/components/Latency/Latency.tsx b/site/src/components/Latency/Latency.tsx
@@ -1,7 +1,11 @@
 import { useTheme } from "@emotion/react";
 import CircularProgress from "@mui/material/CircularProgress";
-import Tooltip from "@mui/material/Tooltip";
 import { Abbr } from "components/Abbr/Abbr";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "components/Tooltip/Tooltip";
 import { CircleHelpIcon } from "lucide-react";
 import type { FC } from "react";
 import { cn } from "utils/cn";
@@ -11,37 +15,50 @@ interface LatencyProps {
 	latency?: number;
 	isLoading?: boolean;
 	className?: string;
-	iconClassName?: string;
 }
 
 export const Latency: FC<LatencyProps> = ({
 	latency,
 	isLoading,
 	className,
-	iconClassName,
 }) => {
 	const theme = useTheme();
 	// Always use the no latency color for loading.
 	const color = getLatencyColor(theme, isLoading ? undefined : latency);
 
 	if (isLoading) {
 		return (
-			<Tooltip title="Loading latency..." className={className}>
-				<CircularProgress
-					className={cn("!size-icon-xs", iconClassName)}
-					style={{ color }}
-				/>
+			<Tooltip>
+				<TooltipTrigger asChild>
+					{/**
+					 * Spinning progress icon must be placed inside a fixed-size container,
+					 * to ensure tooltip remains stationary when opened
+					 */}
+					<div
+						className={cn(
+							"size-4 flex flex-wrap place-content-center",
+							className,
+						)}
+					>
+						<CircularProgress className="!size-icon-xs" style={{ color }} />
+					</div>
+				</TooltipTrigger>
+				<TooltipContent side="bottom">Loading latency...</TooltipContent>
 			</Tooltip>
 		);
 	}
 
 	if (!latency) {
 		return (
-			<Tooltip title="Latency not available" className={className}>
-				<CircleHelpIcon
-					className={cn("!size-icon-sm", iconClassName)}
-					style={{ color }}
-				/>
+			<Tooltip>
+				<TooltipTrigger asChild>
+					<CircleHelpIcon
+						aria-label="Latency not available"
+						className={cn("!size-icon-sm", className)}
+						style={{ color }}
+					/>
+				</TooltipTrigger>
+				<TooltipContent side="bottom">Latency not available</TooltipContent>
 			</Tooltip>
 		);
 	}

diff --git a/site/src/components/SearchField/SearchField.tsx b/site/src/components/SearchField/SearchField.tsx
@@ -1,10 +1,15 @@
 import IconButton from "@mui/material/IconButton";
 import InputAdornment from "@mui/material/InputAdornment";
 import TextField, { type TextFieldProps } from "@mui/material/TextField";
-import Tooltip from "@mui/material/Tooltip";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "components/Tooltip/Tooltip";
 import { useEffectEvent } from "hooks/hookPolyfills";
 import { SearchIcon, XIcon } from "lucide-react";
 import { type FC, useLayoutEffect, useRef } from "react";
+
 export type SearchFieldProps = Omit<TextFieldProps, "onChange"> & {
 	onChange: (query: string) => void;
 	autoFocus?: boolean;
@@ -47,16 +52,19 @@ export const SearchField: FC<SearchFieldProps> = ({
 				),
 				endAdornment: value !== "" && (
 					<InputAdornment position="end">
-						<Tooltip title="Clear search">
-							<IconButton
-								size="small"
-								onClick={() => {
-									onChange("");
-								}}
-							>
-								<XIcon className="size-icon-xs" />
-								<span className="sr-only">Clear search</span>
-							</IconButton>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<IconButton
+									size="small"
+									onClick={() => {
+										onChange("");
+									}}
+								>
+									<XIcon className="size-icon-xs" />
+									<span className="sr-only">Clear search</span>
+								</IconButton>
+							</TooltipTrigger>
+							<TooltipContent side="bottom">Clear search</TooltipContent>
 						</Tooltip>
 					</InputAdornment>
 				),

diff --git a/site/src/components/Tooltip/Tooltip.tsx b/site/src/components/Tooltip/Tooltip.tsx
@@ -14,6 +14,8 @@ export const Tooltip = TooltipPrimitive.Root;
 
 export const TooltipTrigger = TooltipPrimitive.Trigger;
 
+export const TooltipArrow = TooltipPrimitive.Arrow;
+
 export type TooltipContentProps = React.ComponentPropsWithoutRef<
 	typeof TooltipPrimitive.Content
 > & {

diff --git a/site/src/modules/dashboard/Navbar/ProxyMenu.tsx b/site/src/modules/dashboard/Navbar/ProxyMenu.tsx
@@ -112,6 +112,7 @@ export const ProxyMenu: FC<ProxyMenuProps> = ({ proxyContextValue }) => {
 				// to turn this off because otherwise, screen readers will skip over all
 				// the descriptive text and will only have access to the latency options
 				autoFocus={false}
+				className="z-0"
 			>
 				{proxyContextValue.proxies &&
 					proxyContextValue.proxies.length > 1 && [

diff --git a/site/src/modules/dashboard/Navbar/UserDropdown/UserDropdownContent.tsx b/site/src/modules/dashboard/Navbar/UserDropdown/UserDropdownContent.tsx
@@ -6,11 +6,15 @@ import {
 } from "@emotion/react";
 import Divider from "@mui/material/Divider";
 import MenuItem from "@mui/material/MenuItem";
-import Tooltip from "@mui/material/Tooltip";
 import { PopoverClose } from "@radix-ui/react-popover";
 import type * as TypesGen from "api/typesGenerated";
 import { CopyButton } from "components/CopyButton/CopyButton";
 import { Stack } from "components/Stack/Stack";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "components/Tooltip/Tooltip";
 import {
 	CircleUserIcon,
 	LogOutIcon,
@@ -102,23 +106,31 @@ export const UserDropdownContent: FC<UserDropdownContentProps> = ({
 			<Divider css={{ marginBottom: "0 !important" }} />
 
 			<Stack css={styles.info} spacing={0}>
-				<Tooltip title="Browse the source code">
-					<a
-						css={[styles.footerText, styles.buildInfo]}
-						href={buildInfo?.external_url}
-						target="_blank"
-						rel="noreferrer"
-					>
-						{buildInfo?.version} <SquareArrowOutUpRightIcon />
-					</a>
+				<Tooltip>
+					<TooltipTrigger asChild>
+						<a
+							css={[styles.footerText, styles.buildInfo]}
+							href={buildInfo?.external_url}
+							target="_blank"
+							rel="noreferrer"
+						>
+							{buildInfo?.version} <SquareArrowOutUpRightIcon />
+						</a>
+					</TooltipTrigger>
+					<TooltipContent side="bottom">Browse the source code</TooltipContent>
 				</Tooltip>
 
 				{buildInfo?.deployment_id && (
 					<div className="flex items-center text-xs">
-						<Tooltip title="Deployment Identifier">
-							<span className="whitespace-nowrap overflow-hidden text-ellipsis">
-								{buildInfo.deployment_id}
-							</span>
+						<Tooltip>
+							<TooltipTrigger asChild>
+								<span className="whitespace-nowrap overflow-hidden text-ellipsis">
+									{buildInfo.deployment_id}
+								</span>
+							</TooltipTrigger>
+							<TooltipContent side="bottom">
+								Deployment Identifier
+							</TooltipContent>
 						</Tooltip>
 						<CopyButton
 							text={buildInfo.deployment_id}

diff --git a/site/src/modules/provisioners/Provisioner.tsx b/site/src/modules/provisioners/Provisioner.tsx
@@ -1,7 +1,11 @@
 import { useTheme } from "@emotion/react";
-import Tooltip from "@mui/material/Tooltip";
 import type { HealthMessage, ProvisionerDaemon } from "api/typesGenerated";
 import { Pill } from "components/Pill/Pill";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "components/Tooltip/Tooltip";
 import { Building2Icon, UserIcon } from "lucide-react";
 import type { FC } from "react";
 import { createDayString } from "utils/createDayString";
@@ -74,16 +78,19 @@ export const Provisioner: FC<ProvisionerProps> = ({
 						justifyContent: "right",
 					}}
 				>
-					<Tooltip title="Scope">
-						<Pill size="lg" icon={iconScope}>
-							<span
-								css={{
-									":first-letter": { textTransform: "uppercase" },
-								}}
-							>
-								{daemonScope}
-							</span>
-						</Pill>
+					<Tooltip>
+						<TooltipTrigger asChild>
+							<Pill size="lg" icon={iconScope}>
+								<span
+									css={{
+										":first-letter": { textTransform: "uppercase" },
+									}}
+								>
+									{daemonScope}
+								</span>
+							</Pill>
+						</TooltipTrigger>
+						<TooltipContent side="bottom">Scope</TooltipContent>
 					</Tooltip>
 					{extraTags.map(([key, value]) => (
 						<ProvisionerTag key={key} tagName={key} tagValue={value} />

diff --git a/site/src/modules/resources/AgentMetadata.tsx b/site/src/modules/resources/AgentMetadata.tsx
@@ -1,5 +1,4 @@
 import Skeleton from "@mui/material/Skeleton";
-import Tooltip from "@mui/material/Tooltip";
 import { watchAgentMetadata } from "api/api";
 import type {
 	ServerSentEvent,
@@ -8,6 +7,11 @@ import type {
 } from "api/typesGenerated";
 import { displayError } from "components/GlobalSnackbar/utils";
 import { Stack } from "components/Stack/Stack";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipTrigger,
+} from "components/Tooltip/Tooltip";
 import dayjs from "dayjs";
 import {
 	type FC,
@@ -183,10 +187,15 @@ const MetadataItem: FC<MetadataItemProps> = ({ item }) => {
 		status === "loading" ? (
 			<Skeleton width={65} height={12} variant="text" className="mt-[6px]" />
 		) : status === "stale" ? (
-			<Tooltip title="This data is stale and no longer up to date">
-				<StaticWidth className="text-ellipsis overflow-hidden whitespace-nowrap max-w-64 text-sm text-content-disabled cursor-pointer">
-					{item.result.value}
-				</StaticWidth>
+			<Tooltip>
+				<TooltipTrigger asChild>
+					<StaticWidth className="text-ellipsis overflow-hidden whitespace-nowrap max-w-64 text-sm text-content-disabled cursor-pointer">
+						{item.result.value}
+					</StaticWidth>
+				</TooltipTrigger>
+				<TooltipContent side="bottom">
+					This data is stale and no longer up to date
+				</TooltipContent>
 			</Tooltip>
 		) : (
 			<StaticWidth

diff --git a/site/src/modules/resources/AgentRow.stories.tsx b/site/src/modules/resources/AgentRow.stories.tsx
@@ -141,6 +141,13 @@ export const BunchOfApps: Story = {
 	},
 };
 
+export const Disconnected: Story = {
+	args: {
+		agent: M.MockWorkspaceAgentDisconnected,
+		initialMetadata: [],
+	},
+};
+
 export const Connecting: Story = {
 	args: {
 		agent: M.MockWorkspaceAgentConnecting,