Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(web): banner users who opted out of the v4 UI (#19608)

marliessophiea0f5dd522b37
diff --git a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx
index 4c420d1172..be4260f214 100644
--- a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx
+++ b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx
@@ -67,6 +67,10 @@ import {
usePaymentBanner,
} from "@/src/features/payment-banner";
import { useTopBannerHeight } from "@/src/features/top-banner";
+import {
+ LegacyUiBanner,
+ useLegacyUiBannerVisible,
+} from "@/src/features/v4-migration/LegacyUiBanner";
const DISMISSED_SIDEBAR_NOTIFICATIONS_KEY = "dismissed-sidebar-notifications";
@@ -144,14 +148,16 @@ export function AuthenticatedLayout({
const showV4Migration = useV4UpgradeUiFlag();
const { organization: currentOrganization, project: currentProject } =
useQueryProjectOrOrganization();
+ const routerProjectId =
+ typeof router.query.projectId === "string"
+ ? router.query.projectId
+ : undefined;
+ const showLegacyUiBanner = useLegacyUiBannerVisible(routerProjectId);
const customerDataWarning = getCustomerDataWarning({
email: user.email,
isAdmin: user.admin === true,
isLangfuseCloud,
- projectId:
- typeof router.query.projectId === "string"
- ? router.query.projectId
- : null,
+ projectId: routerProjectId ?? null,
organizationId:
typeof router.query.organizationId === "string"
? router.query.organizationId
@@ -316,6 +322,7 @@ export function AuthenticatedLayout({
{customerDataWarning && (
<CustomerDataWarningBannerView {...customerDataWarning} />
)}
+ {showLegacyUiBanner && <LegacyUiBanner />}
{paymentBanner && (
<PaymentBannerView
organizationName={paymentBanner.organizationName}
@@ -342,11 +349,7 @@ export function AuthenticatedLayout({
user={sidebarUser}
userMenuItems={userMenuItems}
isLangfuseCloud={isLangfuseCloud}
- routerProjectId={
- typeof router.query.projectId === "string"
- ? router.query.projectId
- : undefined
- }
+ routerProjectId={routerProjectId}
/>
{/* `min-w-0`, not a `100vw`-derived width: viewport units ignore
scrollbars, and a definite width also floors `min-width:
diff --git a/web/src/features/events/components/V4SidebarToggle.tsx b/web/src/features/events/components/V4SidebarToggle.tsx
index c3d0e98cf3..ea89598b46 100644
--- a/web/src/features/events/components/V4SidebarToggle.tsx
+++ b/web/src/features/events/components/V4SidebarToggle.tsx
@@ -8,161 +8,17 @@ import {
TooltipTrigger,
} from "@/src/components/ui/tooltip";
import { useReadPath } from "@/src/features/events/hooks/useReadPath";
-import { setReadPath } from "@/src/features/events/actions/setReadPath";
-import { usePendingReadPath } from "@/src/features/events/stores/readPathToggleStore";
+import { useV4PreviewToggle } from "@/src/features/events/hooks/useV4PreviewToggle";
import { V4IntroDialog } from "@/src/features/events/components/V4IntroDialog";
-import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
-import {
- getV4PreviewDisabledRedirect,
- getV4PreviewEnabledRedirect,
-} from "@/src/features/events/lib/v4PreviewRedirect";
-import { api } from "@/src/utils/api";
import { ZapIcon } from "@langfuse/icons";
-import { useId, useState } from "react";
+import { useId } from "react";
import { useRouter } from "next/router";
-import { useSession } from "next-auth/react";
-import {
- singleRunToExperimentsUrl,
- toExperimentsResultsUrl,
-} from "@/src/features/experiments/utils/experimentUrlTranslation";
import {
V4_PREVIEW_LABEL,
V4_PREVIEW_DESCRIPTION,
} from "@/src/features/events/lib/v4PreviewLabel";
-function asSingleValue(value: string | string[] | undefined) {
- return Array.isArray(value) ? value[0] : value;
-}
-
-function asArrayValue(value: string | string[] | undefined) {
- if (!value) return [];
- return Array.isArray(value) ? value : [value];
-}
-
-const INTRO_DIALOG_SEEN_KEY = "v4-beta-intro-dialog-seen";
-
-// Shared behavior for every V4 Preview toggle surface: session-backed state,
-// intro dialog on first enable, and the datasets/experiments URL translation
-// that keeps the current page valid after switching. `source` distinguishes
-// the surfaces in the shared v4_beta_toggled event. The commit itself is the
-// shared `setReadPath` workflow; only the intro dialog lives here.
-function useV4PreviewToggle(source: "sidebar" | "migration_panel") {
- const router = useRouter();
- const { isV4 } = useReadPath();
- const pendingReadPath = usePendingReadPath();
- const { update: updateSession } = useSession();
- const mutation = api.userAccount.setV4BetaEnabled.useMutation();
- const capture = usePostHogClientCapture();
-
- const [showIntroDialog, setShowIntroDialog] = useState(false);
- const [pendingAfterToggle, setPendingAfterToggle] = useState<
- (() => Promise<unknown> | void) | undefined
- >();
-
- // The pending intent wins while a toggle is committing, so the switch shows
- // the value the user just chose — and snaps back if the commit fails.
- const isChecked = pendingReadPath ? pendingReadPath === "v4" : isV4;
- const isLoading = pendingReadPath !== null;
-
- // Returns the navigation promise so the pending intent (disabled switch)
- // holds until the redirect lands.
- const redirectAfterToggle = (enabled: boolean): Promise<unknown> | void => {
- const projectId = asSingleValue(router.query.projectId);
- if (!projectId) return;
-
- if (!enabled) {
- const redirect = getV4PreviewDisabledRedirect(router.pathname, projectId);
- if (redirect) return router.push(redirect);
- return;
- }
-
- const evaluatorRedirect = getV4PreviewEnabledRedirect(
- router.pathname,
- projectId,
- );
- if (evaluatorRedirect) {
- return router.push(evaluatorRedirect);
- }
-
- if (
- router.pathname ===
- "/project/[projectId]/datasets/[datasetId]/runs/[runId]"
- ) {
- const runId = asSingleValue(router.query.runId);
- if (runId) {
- return router.push(singleRunToExperimentsUrl(projectId, runId));
- }
- return;
- }
-
- if (
- router.pathname === "/project/[projectId]/datasets/[datasetId]/compare" ||
- router.pathname ===
- "/project/[projectId]/datasets/[datasetId]/compare/charts"
- ) {
- const runIds = asArrayValue(router.query.runs);
- if (runIds.length > 0) {
- return router.push(toExperimentsResultsUrl(projectId, runIds));
- }
- }
- };
-
- const commitToggle = (
- enabled: boolean,
- afterToggle?: () => Promise<unknown> | void,
- ) => {
- setReadPath(enabled ? "v4" : "v3", {
- setV4BetaEnabled: (input) => mutation.mutateAsync(input),
- updateSession,
- onSuccess: () => {
- capture("sidebar:v4_beta_toggled", { enabled, source });
- return afterToggle ? afterToggle() : redirectAfterToggle(enabled);
- },
- });
- };
-
- // afterToggle, when given, replaces the default same-page URL translation
- // and runs only after the toggle actually committed (mutation + session
- // update done, intro dialog confirmed rather than dismissed).
- const handleToggle = (
- enabled: boolean,
- afterToggle?: () => Promise<unknown> | void,
- ) => {
- if (
- enabled &&
- typeof window !== "undefined" &&
- !localStorage.getItem(INTRO_DIALOG_SEEN_KEY)
- ) {
- setPendingAfterToggle(() => afterToggle);
- setShowIntroDialog(true);
- return;
- }
- commitToggle(enabled, afterToggle);
- };
-
- const confirmIntroDialog = () => {
- localStorage.setItem(INTRO_DIALOG_SEEN_KEY, "true");
- setShowIntroDialog(false);
- commitToggle(true, pendingAfterToggle);
- setPendingAfterToggle(undefined);
- };
-
- const dismissIntroDialog = () => {
- setShowIntroDialog(false);
- setPendingAfterToggle(undefined);
- };
-
- return {
- isChecked,
- isLoading,
- handleToggle,
- showIntroDialog,
- confirmIntroDialog,
- dismissIntroDialog,
- };
-}
-
export function V4SidebarToggle() {
const { canToggleV4 } = useReadPath();
// A locked toggle is only shown in the sidebar for one-way recovery.
diff --git a/web/src/features/events/hooks/useV4PreviewToggle.ts b/web/src/features/events/hooks/useV4PreviewToggle.ts
new file mode 100644
index 0000000000..df73dfada5
--- /dev/null
+++ b/web/src/features/events/hooks/useV4PreviewToggle.ts
@@ -0,0 +1,157 @@
+import { useState } from "react";
+import { useRouter } from "next/router";
+import { useSession } from "next-auth/react";
+
+import { setReadPath } from "@/src/features/events/actions/setReadPath";
+import { useReadPath } from "@/src/features/events/hooks/useReadPath";
+import {
+ getV4PreviewDisabledRedirect,
+ getV4PreviewEnabledRedirect,
+} from "@/src/features/events/lib/v4PreviewRedirect";
+import { usePendingReadPath } from "@/src/features/events/stores/readPathToggleStore";
+import {
+ singleRunToExperimentsUrl,
+ toExperimentsResultsUrl,
+} from "@/src/features/experiments/utils/experimentUrlTranslation";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
+import { api } from "@/src/utils/api";
+
+function asSingleValue(value: string | string[] | undefined) {
+ return Array.isArray(value) ? value[0] : value;
+}
+
+function asArrayValue(value: string | string[] | undefined) {
+ if (!value) return [];
+ return Array.isArray(value) ? value : [value];
+}
+
+const INTRO_DIALOG_SEEN_KEY = "v4-beta-intro-dialog-seen";
+
+export type V4PreviewToggleSource =
+ | "sidebar"
+ | "migration_panel"
+ | "legacy_ui_banner";
+
+/**
+ * Shared behavior for every V4 Preview toggle surface: session-backed state,
+ * intro dialog on first enable, and the datasets/experiments URL translation
+ * that keeps the current page valid after switching. `source` distinguishes
+ * the surfaces in the shared v4_beta_toggled event. The commit itself is the
+ * shared `setReadPath` workflow; only the intro dialog lives with each
+ * surface.
+ */
+export function useV4PreviewToggle(source: V4PreviewToggleSource) {
+ const router = useRouter();
+ const { isV4 } = useReadPath();
+ const pendingReadPath = usePendingReadPath();
+ const { update: updateSession } = useSession();
+ const mutation = api.userAccount.setV4BetaEnabled.useMutation();
+ const capture = usePostHogClientCapture();
+
+ const [showIntroDialog, setShowIntroDialog] = useState(false);
+ const [pendingAfterToggle, setPendingAfterToggle] = useState<
+ (() => Promise<unknown> | void) | undefined
+ >();
+
+ // The pending intent wins while a toggle is committing, so the switch shows
+ // the value the user just chose — and snaps back if the commit fails.
+ const isChecked = pendingReadPath ? pendingReadPath === "v4" : isV4;
+ const isLoading = pendingReadPath !== null;
+
+ // Returns the navigation promise so the pending intent (disabled switch)
+ // holds until the redirect lands.
+ const redirectAfterToggle = (enabled: boolean): Promise<unknown> | void => {
+ const projectId = asSingleValue(router.query.projectId);
+ if (!projectId) return;
+
+ if (!enabled) {
+ const redirect = getV4PreviewDisabledRedirect(router.pathname, projectId);
+ if (redirect) return router.push(redirect);
+ return;
+ }
+
+ const evaluatorRedirect = getV4PreviewEnabledRedirect(
+ router.pathname,
+ projectId,
+ );
+ if (evaluatorRedirect) {
+ return router.push(evaluatorRedirect);
+ }
+
+ if (
+ router.pathname ===
+ "/project/[projectId]/datasets/[datasetId]/runs/[runId]"
+ ) {
+ const runId = asSingleValue(router.query.runId);
+ if (runId) {
+ return router.push(singleRunToExperimentsUrl(projectId, runId));
+ }
+ return;
+ }
+
+ if (
+ router.pathname === "/project/[projectId]/datasets/[datasetId]/compare" ||
+ router.pathname ===
+ "/project/[projectId]/datasets/[datasetId]/compare/charts"
+ ) {
+ const runIds = asArrayValue(router.query.runs);
+ if (runIds.length > 0) {
+ return router.push(toExperimentsResultsUrl(projectId, runIds));
+ }
+ }
+ };
+
+ const commitToggle = (
+ enabled: boolean,
+ afterToggle?: () => Promise<unknown> | void,
+ ) => {
+ setReadPath(enabled ? "v4" : "v3", {
+ setV4BetaEnabled: (input) => mutation.mutateAsync(input),
+ updateSession,
+ onSuccess: () => {
+ capture("sidebar:v4_beta_toggled", { enabled, source });
+ return afterToggle ? afterToggle() : redirectAfterToggle(enabled);
+ },
+ });
+ };
+
+ // afterToggle, when given, replaces the default same-page URL translation
+ // and runs only after the toggle actually committed (mutation + session
+ // update done, intro dialog confirmed rather than dismissed).
+ const handleToggle = (
+ enabled: boolean,
+ afterToggle?: () => Promise<unknown> | void,
+ ) => {
+ if (
+ enabled &&
+ typeof window !== "undefined" &&
+ !localStorage.getItem(INTRO_DIALOG_SEEN_KEY)
+ ) {
+ setPendingAfterToggle(() => afterToggle);
+ setShowIntroDialog(true);
+ return;
+ }
+ commitToggle(enabled, afterToggle);
+ };
+
+ const confirmIntroDialog = () => {
+ localStorage.setItem(INTRO_DIALOG_SEEN_KEY, "true");
+ setShowIntroDialog(false);
+ commitToggle(true, pendingAfterToggle);
+ setPendingAfterToggle(undefined);
+ };
+
+ const dismissIntroDialog = () => {
+ setShowIntroDialog(false);
+ setPendingAfterToggle(undefined);
+ };
+
+ return {
+ isChecked,
+ isLoading,
+ handleToggle,
+ showIntroDialog,
+ confirmIntroDialog,
+ dismissIntroDialog,
+ };
+}
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index d8543548d7..f15118a030 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -518,6 +518,8 @@ const events = {
"migrate_evals_with_agent_clicked",
"overview_banner_status_clicked",
"overview_banner_docs_clicked",
+ // Opt-out users on the legacy-UI top strip → migration status page.
+ "legacy_ui_banner_status_clicked",
"panel_docs_link_clicked",
"create_project_keys_clicked",
"panel_opened",
diff --git a/web/src/features/v4-migration/LegacyUiBanner.tsx b/web/src/features/v4-migration/LegacyUiBanner.tsx
new file mode 100644
index 0000000000..f4450e6857
--- /dev/null
+++ b/web/src/features/v4-migration/LegacyUiBanner.tsx
@@ -0,0 +1,58 @@
+import { V4IntroDialog } from "@/src/features/events/components/V4IntroDialog";
+import { useReadPath } from "@/src/features/events/hooks/useReadPath";
+import { useV4PreviewToggle } from "@/src/features/events/hooks/useV4PreviewToggle";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
+import { LegacyUiBannerView } from "@/src/features/v4-migration/LegacyUiBannerView";
+import { useIsForceV3ExperienceSettled } from "@/src/features/v4-migration/useForceV3Experience";
+import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
+import { useHasV4MigrationDeadline } from "@/src/features/v4-migration/V4MigrationContent";
+
+/**
+ * Whether the legacy-UI migration strip should render. Only for users who
+ * are on the legacy read path *and* whose deployment/project still exposes
+ * the v4 migration UI (so enable + `/v4-migration` are real actions). That
+ * gate also excludes force-v3 projects, and waits until the force-v3 query
+ * has settled so those tenants do not flash the strip on first paint.
+ */
+export function useLegacyUiBannerVisible(projectId?: string): boolean {
+ const { isV3Legacy, isResolved } = useReadPath();
+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);
+ const forceV3Settled = useIsForceV3ExperienceSettled(projectId);
+ return isResolved && isV3Legacy && forceV3Settled && v4UpgradeUiEnabled;
+}
+
+/**
+ * Top-of-app strip for users who disabled the v4 UI. Parent gates with
+ * `useLegacyUiBannerVisible`. Primary CTA runs the same enable path as the
+ * sidebar / migration-page toggle so the banner disappears as soon as the
+ * session flips to v4.
+ */
+export function LegacyUiBanner() {
+ const hasDeadline = useHasV4MigrationDeadline();
+ const capture = usePostHogClientCapture();
+ const {
+ isLoading,
+ handleToggle,
+ showIntroDialog,
+ confirmIntroDialog,
+ dismissIntroDialog,
+ } = useV4PreviewToggle("legacy_ui_banner");
+
+ return (
+ <>
+ <LegacyUiBannerView
+ hasDeadline={hasDeadline}
+ isSwitching={isLoading}
+ onSwitchToLatestUi={() => handleToggle(true)}
+ onMigrationStatusClick={() =>
+ capture("v4_migration:legacy_ui_banner_status_clicked")
+ }
+ />
+ <V4IntroDialog
+ open={showIntroDialog}
+ onConfirm={confirmIntroDialog}
+ onDismiss={dismissIntroDialog}
+ />
+ </>
+ );
+}
diff --git a/web/src/features/v4-migration/LegacyUiBannerView.stories.tsx b/web/src/features/v4-migration/LegacyUiBannerView.stories.tsx
new file mode 100644
index 0000000000..9309fed5fe
--- /dev/null
+++ b/web/src/features/v4-migration/LegacyUiBannerView.stories.tsx
@@ -0,0 +1,48 @@
+import { fn } from "storybook/test";
+
+import preview from "../../../.storybook/preview";
+import { LegacyUiBannerView } from "./LegacyUiBannerView";
+
+const meta = preview.meta({
+ component: LegacyUiBannerView,
+ args: {
+ hasDeadline: true,
+ isSwitching: false,
+ onSwitchToLatestUi: fn(),
+ onMigrationStatusClick: fn(),
+ },
+});
+
+/**
+ * Cloud: retirement date included. Blue preview-banner tokens; primary
+ * enables v4; secondary is an underlined link to the migration guide.
+ */
+export const WithDeadline = meta.story({});
+
+/** Self-hosted / no Cloud deadline — date clause omitted. */
+export const WithoutDeadline = meta.story({
+ args: { hasDeadline: false },
+});
+
+/** Primary CTA while the enable mutation / session refresh is in flight. */
+export const Switching = meta.story({
+ args: { isSwitching: true },
+});
+
+/**
+ * Phone width: actions drop under the message (PaymentBanner pattern) so the
+ * copy keeps the full row instead of squeezing beside non-wrapping buttons.
+ */
+export const Narrow = meta.story({
+ globals: { viewport: { value: "legacy-ui-banner-phone", isRotated: false } },
+ parameters: {
+ viewport: {
+ options: {
+ "legacy-ui-banner-phone": {
+ name: "Phone",
+ styles: { width: "390px", height: "844px" },
+ },
+ },
+ },
+ },
+});
diff --git a/web/src/features/v4-migration/LegacyUiBannerView.tsx b/web/src/features/v4-migration/LegacyUiBannerView.tsx
new file mode 100644
index 0000000000..ac61a8133d
--- /dev/null
+++ b/web/src/features/v4-migration/LegacyUiBannerView.tsx
@@ -0,0 +1,58 @@
+import Link from "next/link";
+
+import { Button } from "@/src/components/design-system/Button/Button";
+import { V4_MIGRATION_DEADLINE } from "@/src/features/v4-migration/V4MigrationContent";
+
+export type LegacyUiBannerViewProps = {
+ /** When true, include the Cloud retirement date in the message. */
+ hasDeadline: boolean;
+ /** True while the enable-v4 mutation / session refresh is in flight. */
+ isSwitching: boolean;
+ onSwitchToLatestUi: () => void;
+ /** Fires on the secondary link click (analytics). */
+ onMigrationStatusClick?: () => void;
+};
+
+/**
+ * Full-width top strip for users who opted back to the legacy (v3) UI.
+ * Uses the blue preview-banner tokens. Enable CTA is DS Button outline/sm
+ * (bordered gray, quietest box variant). Below `sm` the actions drop to their
+ * own row (PaymentBanner pattern). Not dismissible.
+ */
+export function LegacyUiBannerView({
+ hasDeadline,
+ isSwitching,
+ onSwitchToLatestUi,
+ onMigrationStatusClick,
+}: LegacyUiBannerViewProps) {
+ return (
+ <div
+ className="border-preview-banner-border bg-preview-banner text-preview-banner-foreground flex w-full flex-col gap-1 border-b px-4 py-1.5 sm:flex-row sm:items-center sm:justify-between sm:gap-3 sm:py-1"
+ role="status"
+ >
+ <p className="min-w-0 flex-1 text-sm wrap-break-word">
+ <span className="font-bold">You are viewing legacy UI.</span>{" "}
+ {hasDeadline
+ ? `It will be retired on ${V4_MIGRATION_DEADLINE}.`
+ : "It will be retired."}
+ </p>
+ <div className="flex shrink-0 items-center gap-3 self-end sm:self-auto">
+ <Button
+ size="sm"
+ variant="outline"
+ text="Switch to latest UI"
+ loading={isSwitching}
+ disabled={isSwitching}
+ onClick={onSwitchToLatestUi}
+ />
+ <Link
+ href="/v4-migration"
+ onClick={onMigrationStatusClick}
+ className="text-preview-banner-link hover:text-preview-banner-link-hover text-sm underline underline-offset-2"
+ >
+ View migration guide
+ </Link>
+ </div>
+ </div>
+ );
+}
diff --git a/web/src/features/v4-migration/useForceV3Experience.ts b/web/src/features/v4-migration/useForceV3Experience.ts
index 6dc11d5e66..3f4a6794a3 100644
--- a/web/src/features/v4-migration/useForceV3Experience.ts
+++ b/web/src/features/v4-migration/useForceV3Experience.ts
@@ -1,13 +1,7 @@
import { api } from "@/src/utils/api";
-/**
- * Whether the given project is forced onto the v3 experience via
- * LANGFUSE_FORCE_V3_EXPERIENCE. The value is static per deployment, so it is
- * cached for the session. Returns false while loading or when no project id is
- * available (safe default: not forced).
- */
-export function useForceV3Experience(projectId?: string): boolean {
- const forceV3 = api.v4Transition.forceV3Experience.useQuery(
+function useForceV3ExperienceQuery(projectId?: string) {
+ return api.v4Transition.forceV3Experience.useQuery(
{ projectId: projectId ?? "" },
{
// Callers that only need the value behind another gate (e.g. the v4
@@ -17,5 +11,29 @@ export function useForceV3Experience(projectId?: string): boolean {
staleTime: Infinity,
},
);
+}
+
+/**
+ * Whether the given project is forced onto the v3 experience via
+ * LANGFUSE_FORCE_V3_EXPERIENCE. The value is static per deployment, so it is
+ * cached for the session. Returns false while loading or when no project id is
+ * available (safe default: not forced).
+ */
+export function useForceV3Experience(projectId?: string): boolean {
+ const forceV3 = useForceV3ExperienceQuery(projectId);
return forceV3.data ?? false;
}
+
+/**
+ * True once the force-v3 query has a definitive answer for this project, or
+ * when there is no project id (nothing to wait for). Use before showing
+ * surfaces that would flash for force-v3 tenants while the default is
+ * "not forced".
+ */
+export function useIsForceV3ExperienceSettled(projectId?: string): boolean {
+ const forceV3 = useForceV3ExperienceQuery(projectId);
+ if (!projectId) {
+ return true;
+ }
+ return forceV3.isFetched;
+}