Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

fix(board): paint image background before video HEAD resolves (#7400)

Octopus-98e164b0bc8a3e
diff --git a/apps/nextjs/src/app/[locale]/boards/[name]/settings/_background.tsx b/apps/nextjs/src/app/[locale]/boards/[name]/settings/_background.tsx
index d734aeeda..e8ffc901b 100644
--- a/apps/nextjs/src/app/[locale]/boards/[name]/settings/_background.tsx
+++ b/apps/nextjs/src/app/[locale]/boards/[name]/settings/_background.tsx
@@ -163,7 +163,6 @@ const ImagePreview = ({ src, w, h }: ImagePreviewProps) => {
return <IconPhotoOff size={w} />;
}
- if (isVideo === undefined) return <IconPhotoOff size={w} />;
if (isVideo) {
return <video src={src} muted preload="metadata" style={{ width: w, height: h, objectFit: "contain" }} />;
}
diff --git a/apps/nextjs/src/components/layout/background.spec.tsx b/apps/nextjs/src/components/layout/background.spec.tsx
new file mode 100644
index 000000000..b63fd10ba
--- /dev/null
+++ b/apps/nextjs/src/components/layout/background.spec.tsx
@@ -0,0 +1,163 @@
+import { createElement, act } from "react";
+import { createRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { BoardBackgroundVideo, useOptionalBackgroundProps } from "./background";
+
+const board = vi.hoisted(() => ({
+ current: {
+ backgroundImageUrl: null as string | null,
+ backgroundImageSize: "cover",
+ backgroundImageRepeat: "no-repeat",
+ backgroundImageAttachment: "fixed",
+ },
+}));
+
+const pathname = vi.hoisted(() => ({ current: "/boards/home" }));
+
+vi.mock("next/navigation", () => ({
+ usePathname: () => pathname.current,
+}));
+
+vi.mock("@homarr/boards/context", () => ({
+ useOptionalBoard: () => board.current,
+}));
+
+vi.mock("@mantine/hooks", () => ({
+ useReducedMotion: () => false,
+}));
+
+const BackgroundProbe = () => {
+ const props = useOptionalBackgroundProps();
+ return createElement(
+ "div",
+ {
+ "data-bg": props.bg ?? "",
+ "data-size": props.bgsz ?? "",
+ "data-attachment": props.bga ?? "",
+ },
+ createElement(BoardBackgroundVideo),
+ );
+};
+
+const headResponse = (contentType: string, status = 200) =>
+ new Response(null, { status, headers: { "content-type": contentType } });
+
+describe("board background", () => {
+ let container: HTMLDivElement;
+ let root: Root;
+ let resolveHead: (response: Response) => void;
+ let rejectHead: (error: unknown) => void;
+
+ beforeEach(() => {
+ container = document.createElement("div");
+ document.body.append(container);
+ root = createRoot(container);
+ board.current = {
+ backgroundImageUrl: "/api/user-medias/background",
+ backgroundImageSize: "cover",
+ backgroundImageRepeat: "no-repeat",
+ backgroundImageAttachment: "fixed",
+ };
+ pathname.current = "/boards/home";
+ resolveHead = () => {};
+ rejectHead = () => {};
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(
+ () =>
+ new Promise<Response>((resolve, reject) => {
+ resolveHead = resolve;
+ rejectHead = reject;
+ }),
+ ),
+ );
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+ vi.unstubAllGlobals();
+ });
+
+ const renderBackground = () => {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ act(() => {
+ root.render(createElement(QueryClientProvider, { client: queryClient }, createElement(BackgroundProbe)));
+ });
+ };
+
+ const backgroundUrl = () => container.querySelector("[data-bg]")?.getAttribute("data-bg");
+ const video = () => container.querySelector("video");
+
+ test("paints an extensionless image before the content-type probe resolves", async () => {
+ renderBackground();
+
+ expect(backgroundUrl()).toBe("url(/api/user-medias/background)");
+ expect(container.querySelector("[data-size]")?.getAttribute("data-size")).toBe("cover");
+ expect(container.querySelector("[data-attachment]")?.getAttribute("data-attachment")).toBe("fixed");
+ expect(video()).toBeNull();
+ expect(fetch).toHaveBeenCalledWith("/api/user-medias/background", expect.objectContaining({ method: "HEAD" }));
+
+ await act(async () => {
+ resolveHead(headResponse("image/jpeg"));
+ });
+
+ expect(backgroundUrl()).toBe("url(/api/user-medias/background)");
+ expect(video()).toBeNull();
+ });
+
+ test("swaps an extensionless upload to video only after HEAD reports video/*", async () => {
+ board.current.backgroundImageUrl = "/api/user-medias/clip";
+ renderBackground();
+
+ expect(backgroundUrl()).toBe("url(/api/user-medias/clip)");
+ expect(video()).toBeNull();
+
+ await act(async () => {
+ resolveHead(headResponse("video/webm; charset=binary"));
+ });
+
+ await vi.waitFor(() => {
+ expect(backgroundUrl()).toBe("");
+ expect(video()?.getAttribute("src")).toBe("/api/user-medias/clip");
+ expect(video()?.muted).toBe(true);
+ expect(video()?.loop).toBe(true);
+ });
+ });
+
+ test.each(["mp4", "webm", "ogg"])("renders a .%s background as video without waiting for HEAD", async (format) => {
+ board.current.backgroundImageUrl = `https://cdn.example/background.${format}?token=1`;
+ renderBackground();
+ await act(async () => {
+ await Promise.resolve();
+ });
+
+ expect(fetch).not.toHaveBeenCalled();
+ expect(backgroundUrl()).toBe("");
+ expect(video()?.getAttribute("src")).toBe(`https://cdn.example/background.${format}?token=1`);
+ });
+
+ test("keeps the image background when the probe fails", async () => {
+ renderBackground();
+
+ await act(async () => {
+ rejectHead(new Error("network down"));
+ });
+
+ expect(backgroundUrl()).toBe("url(/api/user-medias/background)");
+ expect(video()).toBeNull();
+ });
+
+ test("does not apply the shell background outside the board page", () => {
+ pathname.current = "/boards/home/settings";
+ renderBackground();
+
+ expect(backgroundUrl()).toBe("");
+ expect(video()).toBeNull();
+ });
+});
diff --git a/apps/nextjs/src/components/layout/background.tsx b/apps/nextjs/src/components/layout/background.tsx
index a4c24b34f..84ca5be25 100644
--- a/apps/nextjs/src/components/layout/background.tsx
+++ b/apps/nextjs/src/components/layout/background.tsx
@@ -11,9 +11,11 @@ const isVideoUrl = (url: string) =>
export const useIsVideo = (url: string | null | undefined) => {
const canDetectContentType = Boolean(url && /^(\/|https?:\/\/)/.test(url));
+ const extensionIsVideo = Boolean(url && isVideoUrl(url));
const { data, isError } = useQuery({
queryKey: ["background-content-type", url],
- enabled: canDetectContentType,
+ // mp4, webm, and ogg already identify a video, so only ambiguous URLs are probed.
+ enabled: canDetectContentType && !extensionIsVideo,
staleTime: Infinity,
retry: false,
queryFn: async ({ signal }) => {
@@ -28,8 +30,10 @@ export const useIsVideo = (url: string | null | undefined) => {
},
});
if (!canDetectContentType) return false;
+ if (extensionIsVideo) return true;
if (isError) return isVideoUrl(url ?? "");
- return data;
+ // An in-flight probe stays an image until HEAD reports video/*.
+ return data ?? false;
};
export const useOptionalBackgroundProps = (): Partial<AppShellProps> => {
@@ -42,7 +46,8 @@ export const useOptionalBackgroundProps = (): Partial<AppShellProps> => {
// Check if we are on a client board page
if (pathname.split("/").length > 3) return {};
- if (isVideo !== false) {
+ // Keep the image background up while the probe is in flight. Remove it once the URL is a video.
+ if (isVideo) {
return {};
}