From 13b5c80c90cc01ab3705576b57939ff230bf2d7a Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Thu, 27 Aug 2026 15:38:14 -0700
Subject: [PATCH] fix(ui): withhold the tag list until it resolves

The usage page seeded its tag list as an empty array, so between first
paint and the tag request landing the filter had a resolved-looking empty
list and showed "No tags with usage in this range" for a scope nobody had
measured yet.

Seed it as null instead, which the filter already treats as unresolved and
hides, so the empty state only appears once the list has actually come back.
---
 .../components/UsagePageView.test.tsx         | 24 +++++++++++++++++++
 .../_components/components/UsagePageView.tsx  |  2 +-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.test.tsx
index 118371aa9ac..f2dc56af9c5 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.test.tsx
@@ -586,6 +586,30 @@ describe("UsagePage", () => {
     });
   });
 
+  it("should withhold the tag list until it resolves so no empty state is shown while loading", async () => {
+    let resolveTagList: (tags: Record<string, unknown>) => void = () => {};
+    mockTagListCall.mockReturnValue(
+      new Promise((resolve) => {
+        resolveTagList = resolve;
+      }) as ReturnType<typeof networking.tagListCall>,
+    );
+
+    renderWithProviders(<UsagePage {...defaultProps} />);
+
+    act(() => {
+      fireEvent.change(screen.getByTestId("usage-view-select"), { target: { value: "tag" } });
+    });
+
+    const entityUsage = await screen.findByTestId("entity-usage");
+    expect(entityUsage).toHaveAttribute("data-entity-list", "null");
+
+    await act(async () => {
+      resolveTagList({});
+    });
+
+    expect(screen.getByTestId("entity-usage")).toHaveAttribute("data-entity-list", "[]");
+  });
+
   it("should show tag usage selector option for internal users", async () => {
     mockUseAuthorized.mockReturnValue({
       isLoading: false,
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
index c742b3af7e9..0d1e557a833 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/UsagePageView.tsx
@@ -96,7 +96,7 @@ const UsagePage: React.FC<UsagePageProps> = ({ teams, organizations }) => {
     to: initialToDate,
   });
 
-  const [allTags, setAllTags] = useState<EntityList[]>([]);
+  const [allTags, setAllTags] = useState<EntityList[] | null>(null);
   const { data: customers = [] } = useCustomers();
   const { data: agentsResponse } = useAgents();
   const { data: currentUser } = useCurrentUser();