From 10cedbd906e1e2629b8a4b1bc5e2e49bdccc38fb Mon Sep 17 00:00:00 2001
From: Thomas Camlong <thomas@ajnart.fr>
Date: Fri, 22 May 2026 11:37:51 +0200
Subject: [PATCH] fix(widgets): eliminate layout shift with fallback dimensions

Provide estimated width/height to widgets before useElementSize
measures the DOM, preventing responsive breakpoint shifts during
hydration. Replace the Loader spinner with a Skeleton for widget
loading states.
---
 apps/nextjs/src/components/board/items/item-content.tsx | 9 ++++++++-
 packages/widgets/src/index.tsx                          | 8 ++------
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/apps/nextjs/src/components/board/items/item-content.tsx b/apps/nextjs/src/components/board/items/item-content.tsx
index d61d05902..d27e92d44 100644
--- a/apps/nextjs/src/components/board/items/item-content.tsx
+++ b/apps/nextjs/src/components/board/items/item-content.tsx
@@ -27,10 +27,17 @@ const getOverflowFromKind = (kind: SectionItem["kind"]) => {
   return undefined;
 };
 
+const ASSUMED_VIEWPORT_WIDTH = 900;
+const DEFAULT_COLUMN_COUNT = 12;
+
 export const BoardItemContent = ({ item }: BoardItemContentProps) => {
   const { ref, width, height } = useElementSize<HTMLDivElement>();
   const board = useRequiredBoard();
 
+  const estimatedCellSize = ASSUMED_VIEWPORT_WIDTH / DEFAULT_COLUMN_COUNT;
+  const fallbackWidth = item.width * estimatedCellSize - 20;
+  const fallbackHeight = item.height * estimatedCellSize - 20;
+
   return (
     <>
       <Card
@@ -53,7 +60,7 @@ export const BoardItemContent = ({ item }: BoardItemContentProps) => {
         }}
         p={0}
       >
-        <InnerContent item={item} width={width} height={height} />
+        <InnerContent item={item} width={width || fallbackWidth} height={height || fallbackHeight} />
       </Card>
       {item.advancedOptions.title?.trim() && (
         <Badge
diff --git a/packages/widgets/src/index.tsx b/packages/widgets/src/index.tsx
index 572f70aa4..f1e6296f2 100644
--- a/packages/widgets/src/index.tsx
+++ b/packages/widgets/src/index.tsx
@@ -1,7 +1,7 @@
 import type { ComponentType } from "react";
 import type { Loader } from "next/dynamic";
 import dynamic from "next/dynamic";
-import { Center, Loader as UiLoader } from "@mantine/core";
+import { Skeleton } from "@mantine/core";
 
 import { objectEntries } from "@homarr/common";
 import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
@@ -107,11 +107,7 @@ export const loadWidgetDynamic = <TKind extends WidgetKind>(kind: TKind) => {
   const newlyLoadedComponent = dynamic<WidgetComponentProps<TKind>>(
     widgetImports[kind].componentLoader as Loader<WidgetComponentProps<TKind>>,
     {
-      loading: () => (
-        <Center w="100%" h="100%">
-          <UiLoader />
-        </Center>
-      ),
+      loading: () => <Skeleton w="100%" h="100%" radius="md" animate />,
     },
   );