From 18263e4878c5f963a447cba8a154d324c96969df Mon Sep 17 00:00:00 2001
From: Aarnav Tale <git@tale.me>
Date: Mon, 22 Jun 2026 20:22:50 -0400
Subject: [PATCH] fix(ui): show display names in lists

Closes HP-549.
---
 CHANGELOG.md                                       |  1 +
 app/routes/users/components/headplane-user-row.tsx |  6 ++++++
 app/routes/users/components/headscale-user-row.tsx | 12 ++++++------
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d953bc..86c4837 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
 - Added support for proxy authentication via `server.proxy_auth` (closes [#353](https://github.com/tale/headplane/issues/353)).
 - Added automatic role assignment for new OIDC users via `oidc.default_role` and IdP-provided role claims via `oidc.role_claim` (closes [#352](https://github.com/tale/headplane/issues/352)).
 - Fixed the DNS page crashing when Headscale has no Split DNS nameservers configured (closes [#570](https://github.com/tale/headplane/issues/570)).
+- User lists now show Headscale display names while preserving usernames as secondary text (closes [#571](https://github.com/tale/headplane/issues/571)).
 
 ---
 
diff --git a/app/routes/users/components/headplane-user-row.tsx b/app/routes/users/components/headplane-user-row.tsx
index b3e686b..0d3cf6c 100644
--- a/app/routes/users/components/headplane-user-row.tsx
+++ b/app/routes/users/components/headplane-user-row.tsx
@@ -27,6 +27,11 @@ export default function HeadplaneUserRow({
   );
 
   const displayName = user.linkedHeadscaleUser?.displayName || user.name || user.email || user.sub;
+  const displayUsername =
+    user.linkedHeadscaleUser?.displayName &&
+    user.linkedHeadscaleUser.displayName !== user.linkedHeadscaleUser.name
+      ? user.linkedHeadscaleUser.name
+      : undefined;
   const displayEmail = user.linkedHeadscaleUser?.email ?? user.email;
 
   return (
@@ -40,6 +45,7 @@ export default function HeadplaneUserRow({
           )}
           <div className="ml-4">
             <p className="leading-snug font-semibold">{displayName}</p>
+            {displayUsername && <p className="text-sm opacity-50">{displayUsername}</p>}
             {displayEmail && <p className="text-sm opacity-50">{displayEmail}</p>}
             {!user.headscaleUserId && (
               <p className="text-xs text-amber-600 dark:text-amber-400">Not linked</p>
diff --git a/app/routes/users/components/headscale-user-row.tsx b/app/routes/users/components/headscale-user-row.tsx
index 8d74d28..699e7ca 100644
--- a/app/routes/users/components/headscale-user-row.tsx
+++ b/app/routes/users/components/headscale-user-row.tsx
@@ -17,22 +17,22 @@ export default function HeadscaleUserRow({ user, writable }: HeadscaleUserRowPro
     (acc, machine) => Math.max(acc, new Date(machine.lastSeen).getTime()),
     0,
   );
+  const displayName = user.displayName || user.name;
+  const displayUsername =
+    user.displayName && user.displayName !== user.name ? user.name : undefined;
 
   return (
     <tr className="group hover:bg-mist-50 dark:hover:bg-mist-950" key={user.id}>
       <td className="py-2 pl-0.5">
         <div className="flex items-center">
           {user.profilePicUrl ? (
-            <img
-              alt={user.name || user.displayName}
-              className="h-10 w-10 rounded-full"
-              src={user.profilePicUrl}
-            />
+            <img alt={displayName} className="h-10 w-10 rounded-full" src={user.profilePicUrl} />
           ) : (
             <CircleUser className="h-10 w-10" />
           )}
           <div className="ml-4">
-            <p className="leading-snug font-semibold">{user.name || user.displayName}</p>
+            <p className="leading-snug font-semibold">{displayName}</p>
+            {displayUsername && <p className="text-sm opacity-50">{displayUsername}</p>}
             {user.email && <p className="text-sm opacity-50">{user.email}</p>}
           </div>
         </div>