test: align grid footprint expectations

This reverts commit 63f5c43b69.

apps/docs/docs/getting-started/after-the-installation.mdx

@@ -198,9 +198,13 @@ In the modal you can edit the app that you want to display:
 
 <figure>
   <img src={editItemCurrent} alt="Current Edit item modal for an App tile" style={{ maxWidth: "620px" }} />
-  <figcaption>Use the Edit item modal to choose the app and configure how its tile is displayed.</figcaption>
+  <figcaption>
+    The Edit item workspace previews option changes as you configure the tile. Save changes to apply them to the board.
+  </figcaption>
 </figure>
 
+When adding a widget, set its initial grid width and height directly in the preview. These size controls are only shown before the widget is added.
+
 As soon as you save your changes, the tile on the board will refresh and display your app.
 Resize from any visible edge or corner handle. For a Container, activate its top-left grip before using its resize handles.
 Press and hold a handle, move the pointer, and release it when the tile has the size you want.

apps/docs/docs/management/boards/index.mdx

@@ -27,9 +27,10 @@ opening it. Containers include their visible widgets and app icons instead of ap
 
 Names of boards must be unique because this will be used in the URL to load the desired board.
 
-Press `Shift+C`, or select **Switch board** from the user menu, to open the board switcher. It shows
+Press `Shift+C`, or select **Switch board** from the user menu, to open the board switcher. It shows structural
-structural previews of the other boards you can access. Start typing to filter by name, use the arrow keys to move
+previews of every board you can access, with your current board at the end. Home-board markers and creator avatars
-through the results, and press `Enter` to open the selected board.
+match the board management view. Use the search field at the top, or simply start typing, to filter by name. Use the
+arrow keys to move through the results and press `Enter` to open the selected board.
 
 ## Create a new board
 

apps/docs/docs/widgets/bookmarks/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Bookmarks"
-description: "Displays multiple app links"
+description: "Keeps useful links together"
 hide_title: true
 ---
 
@@ -13,11 +13,12 @@ import { bookmarksWidget } from ".";
 
 <WidgetHeader widget={bookmarksWidget} categories={["Links", "Apps"]} />
 
-The bookmarks widget allows you to display multiple links in a single widget.
+The bookmarks widget keeps direct URLs and Homarr Apps in one ordered list.
-Select one or more existing Apps directly in the widget settings; these bookmarks keep a reference to the App, so changes to its name, icon, or URL are reflected automatically.
+Paste a URL and press Enter, paste several comma-separated or one-per-line URLs, or search for an existing App.
-For links that do not need an App, add their URLs under **Custom links** instead.
+URLs do not need an App record; Homarr uses the site's favicon and falls back to a link icon when it cannot load one.
-Its normal view adapts each configured layout to the available width and height: lower-priority hostnames are hidden before names or icons, and larger collections scroll instead of crushing cards.
+Bookmarks selected from Apps continue to use the App name, URL, icon, and description.
-Advanced view shows every bookmark as a roomy card with its full title, hostname, icon, and complete description regardless of the compact layout and visibility choices.
+
+**Adaptive** layout is the practical default: it changes between icons, compact rows, and tiles as the widget changes shape. Every compact item exposes its destination on hover, while advanced view expands items into descriptive cards.
 
 ### Screenshots
 

apps/docs/docs/widgets/bookmarks/index.ts

@@ -4,7 +4,7 @@ import { IconBookmark } from "@tabler/icons-react";
 export const bookmarksWidget: WidgetDefinition = {
   icon: IconBookmark,
   name: "Bookmarks",
-  description: "Displays multiple app links",
+  description: "Keeps useful links together",
   path: "../../widgets/bookmarks",
   configuration: {
     items: [
@@ -16,9 +16,21 @@ export const bookmarksWidget: WidgetDefinition = {
       },
       {
         name: "Layout",
-        description: "Layout in which the bookmarks are displayed.",
+        description: "How bookmarks use the available widget space.",
-        values: { type: "select", options: ["Vertical", "Horizontal", "Grid", "Grid horizontal"] },
+        values: { type: "select", options: ["Adaptive", "Vertical", "Horizontal", "Grid", "Compact grid", "Icons"] },
-        defaultValue: "Vertical",
+        defaultValue: "Adaptive",
+      },
+      {
+        name: "Appearance",
+        description: "Card surface style.",
+        values: { type: "select", options: ["Soft", "Filled", "Outline", "Plain"] },
+        defaultValue: "Soft",
+      },
+      {
+        name: "Card spacing",
+        description: "Space between bookmark cards.",
+        values: { type: "select", options: ["Extra small", "Small", "Medium", "Large", "Extra large"] },
+        defaultValue: "Extra small",
       },
       {
         name: "Hide title",
@@ -46,16 +58,10 @@ export const bookmarksWidget: WidgetDefinition = {
       },
       {
         name: "Bookmarks",
-        description: "List of bookmarks to display in the widget.",
+        description: "URLs and existing Apps shown by the widget.",
-        values: "Select one or more Apps directly, then order them as you like.",
+        values: "Paste one or many URLs, or find an existing App. Drag to reorder.",
         defaultValue: "No bookmarks selected",
       },
-      {
-        name: "Custom links",
-        description: "URLs to display without first creating an App.",
-        values: "List of URLs.",
-        defaultValue: "No custom links",
-      },
     ],
   },
 };

apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx

@@ -16,7 +16,7 @@ import { BoardSetupChecklist } from "~/components/board/board-setup-checklist";
 import {
   getBoardLaneColumnCount,
   getInitialBoardLogicalHeight,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   LOGICAL_GRID_GAP,
   getRootSectionForLane,
 } from "~/components/board/layout";
@@ -61,16 +61,16 @@ export const ClientBoard = () => {
   const rightColumnCount = getBoardLaneColumnCount(currentLayout, "right");
   const laneWidths = [leftColumnCount, mainColumnCount, rightColumnCount]
     .filter((columnCount) => columnCount > 0)
-    .map(getLogicalTrackSize);
+    .map(getLogicalGridSize);
   const logicalWidth =
     laneWidths.reduce((total, width) => total + width, 0) + (laneWidths.length - 1) * LOGICAL_GRID_GAP;
   const initialLogicalHeight = getInitialBoardLogicalHeight(board, currentLayoutId);
   const representativeWidth = layoutOverrideId ? getRepresentativeLayoutWidth(currentLayout, board.layouts) : null;
   const initialAvailableWidth = Math.max(1, (representativeWidth ?? initialViewportWidth) - APP_SHELL_INLINE_PADDING);
   const gridTemplateColumns = [
-    leftColumnCount > 0 ? `${getLogicalTrackSize(leftColumnCount)}px` : null,
+    leftColumnCount > 0 ? `${getLogicalGridSize(leftColumnCount)}px` : null,
-    `${getLogicalTrackSize(mainColumnCount)}px`,
+    `${getLogicalGridSize(mainColumnCount)}px`,
-    rightColumnCount > 0 ? `${getLogicalTrackSize(rightColumnCount)}px` : null,
+    rightColumnCount > 0 ? `${getLogicalGridSize(rightColumnCount)}px` : null,
   ]
     .filter((value) => value !== null)
     .join(" ");

apps/nextjs/src/app/[locale]/widgets/[kind]/_content.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+/* eslint-disable react/no-unstable-nested-components -- Widget modules and definition-bound fallbacks are loaded dynamically. */
+
 import { use, useCallback, useState } from "react";
 import { ActionIcon, Affix, Card } from "@mantine/core";
 import { IconDimensions, IconPencil, IconToggleLeft, IconToggleRight } from "@tabler/icons-react";
@@ -71,6 +73,7 @@ export const WidgetPreviewPageContent = ({ kind }: WidgetPreviewPageContentProps
           ),
           integrationSupport: hasIntegrationSupport,
           settings,
+          previewDimensions: dimensions,
         },
         {
           title(translate) {
@@ -86,10 +89,10 @@ export const WidgetPreviewPageContent = ({ kind }: WidgetPreviewPageContentProps
     } finally {
       setIsEditorLoading(false);
     }
-  }, [currentDefinition, kind, openWidgetEditModal, settings, state, t, utils]);
+  }, [currentDefinition, dimensions, kind, openWidgetEditModal, settings, state, t, utils]);
 
   const toggleEditMode = useCallback(() => {
-    setEditMode((editMode) => !editMode);
+    setEditMode((currentEditMode) => !currentEditMode);
     showSuccessNotification({
       message: editMode ? t("widgetPreview.toggle.disabled") : t("widgetPreview.toggle.enabled"),
     });

apps/nextjs/src/app/[locale]/widgets/[kind]/page.tsx

@@ -1,8 +1,14 @@
 import { Suspense } from "react";
-import { notFound } from "next/navigation";
+import { notFound, redirect } from "next/navigation";
 import { Center, Loader } from "@mantine/core";
 
+import { getHomeBoardAsync } from "@homarr/api/board-server";
+import { IntegrationProvider } from "@homarr/auth/client";
+import { auth } from "@homarr/auth/next";
+import { getIntegrationsWithPermissionsAsync } from "@homarr/auth/server";
+import { BoardPreviewProvider } from "@homarr/boards/context";
 import type { WidgetKind } from "@homarr/definitions";
+import { ModalProvider } from "@homarr/modals";
 import { widgetKinds } from "@homarr/widgets/manifest";
 
 import { WidgetPreviewPageContent } from "./_content";
@@ -16,12 +22,24 @@ export default async function WidgetPreview(props: Props) {
   if (!widgetKinds.includes(kind as WidgetKind)) {
     notFound();
   }
+  const session = await auth();
+  if (!session) {
+    redirect(`/auth/login?callbackUrl=${encodeURIComponent(`/widgets/${kind}`)}`);
+  }
+
+  const [integrations, board] = await Promise.all([getIntegrationsWithPermissionsAsync(session), getHomeBoardAsync()]);
 
   return (
-    <Center h="100vh">
+    <IntegrationProvider integrations={integrations}>
-      <Suspense fallback={<Loader size="sm" />}>
+      <BoardPreviewProvider board={board}>
-        <WidgetPreviewPageContent key={kind} kind={kind as WidgetKind} />
+        <ModalProvider>
-      </Suspense>
+          <Center h="100vh">
-    </Center>
+            <Suspense fallback={<Loader size="sm" />}>
+              <WidgetPreviewPageContent key={kind} kind={kind as WidgetKind} />
+            </Suspense>
+          </Center>
+        </ModalProvider>
+      </BoardPreviewProvider>
+    </IntegrationProvider>
   );
 }

apps/nextjs/src/components/board/board-layout-thumbnail.module.css

@@ -1,5 +1,6 @@
 .canvas {
-  min-height: 8rem;
+  width: 100%;
+  min-width: 0;
   aspect-ratio: 16 / 7;
   overflow: hidden;
   color: var(--mantine-color-dimmed);
@@ -83,9 +84,3 @@
   gap: rem(1px);
   overflow: hidden;
 }
-
-@media (max-width: $mantine-breakpoint-xs) {
-  .canvas {
-    min-height: 7rem;
-  }
-}

apps/nextjs/src/components/board/board-layout-thumbnail.tsx

@@ -11,11 +11,12 @@ import classes from "./board-layout-thumbnail.module.css";
 interface BoardLayoutThumbnailProps {
   preview: BoardPreviewData | null;
   label: string;
+  fitFullLayout?: boolean;
 }
 
 const maxThumbnailRows = 12;
 
-export const BoardLayoutThumbnail = ({ preview, label }: BoardLayoutThumbnailProps) => {
+export const BoardLayoutThumbnail = ({ preview, label, fitFullLayout = false }: BoardLayoutThumbnailProps) => {
   const layout = preview?.layouts.find((candidate) => candidate.role === "base") ?? preview?.layouts.at(0);
   if (!preview || !layout) {
     return (
@@ -26,6 +27,7 @@ export const BoardLayoutThumbnail = ({ preview, label }: BoardLayoutThumbnailPro
   }
 
   const elements = projectBoardLayout(preview, layout, layout);
+  const thumbnailRowLimit = fitFullLayout ? Number.POSITIVE_INFINITY : maxThumbnailRows;
   const roots = preview.sections
     .filter((section) => section.kind === "empty")
     .toSorted((first, second) => (first.xOffset ?? 0) - (second.xOffset ?? 0) || first.id.localeCompare(second.id));
@@ -65,12 +67,12 @@ export const BoardLayoutThumbnail = ({ preview, label }: BoardLayoutThumbnailPro
               element.xOffset >= 0 &&
               element.xOffset < columnCount &&
               element.yOffset >= 0 &&
-              element.yOffset < maxThumbnailRows &&
+              element.yOffset < thumbnailRowLimit &&
               element.width > 0 &&
               element.height > 0,
           );
           const rowCount = Math.min(
-            maxThumbnailRows,
+            thumbnailRowLimit,
             Math.max(4, ...laneElements.map((element) => element.yOffset + element.height)),
           );
 

apps/nextjs/src/components/board/board-switcher.module.css

@@ -1,7 +1,26 @@
+.modalContent {
+  overflow: hidden;
+  border: rem(1px) solid color-mix(in srgb, var(--mantine-color-default-border) 70%, transparent);
+  border-radius: rem(24px);
+  background: color-mix(in srgb, var(--mantine-color-body) 58%, transparent);
+  box-shadow: 0 rem(18px) rem(56px) rgb(0 0 0 / 22%);
+  backdrop-filter: blur(rem(20px)) saturate(140%);
+}
+
+.modalBody {
+  padding: var(--mantine-spacing-sm);
+}
+
 .content {
   outline: none;
 }
 
+.searchInput {
+  border-color: color-mix(in srgb, var(--mantine-color-default-border) 72%, transparent);
+  background: color-mix(in srgb, var(--mantine-color-body) 54%, transparent);
+  backdrop-filter: blur(rem(8px));
+}
+
 .option {
   min-width: 0;
   border-radius: var(--mantine-radius-md);
@@ -11,6 +30,12 @@
 .card {
   height: 100%;
   overflow: hidden;
+  box-shadow: var(--mantine-shadow-sm);
+}
+
+.metadataBadge {
+  width: rem(22px);
+  padding-inline: 0;
 }
 
 .option:hover .card,

apps/nextjs/src/components/board/board-switcher.tsx

@@ -3,29 +3,31 @@
 import type { KeyboardEvent, ReactNode, RefObject } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
+  Badge,
   Card,
   Center,
   Group,
-  Kbd,
   Loader,
   Modal,
   ScrollArea,
   SimpleGrid,
   Stack,
   Text,
+  TextInput,
   ThemeIcon,
+  Tooltip,
   UnstyledButton,
   useMatches,
   VisuallyHidden,
 } from "@mantine/core";
 import { useHotkeys } from "@mantine/hooks";
-import { IconArrowDown, IconArrowRight, IconLayoutBoard, IconReplace } from "@tabler/icons-react";
+import { IconDeviceMobile, IconHomeFilled, IconLayoutBoard, IconSearch } from "@tabler/icons-react";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { useOptionalBoard } from "@homarr/boards/context";
 import { useI18n } from "@homarr/translation/client";
-import { Link } from "@homarr/ui";
+import { Link, UserAvatar } from "@homarr/ui";
 
 import { BoardLayoutThumbnail } from "~/components/board/board-layout-thumbnail";
 
@@ -39,6 +41,7 @@ interface BoardSwitcherProps {
 
 export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
   const t = useI18n("board.action.switcher");
+  const manageBoardsT = useI18n("management.page.board");
   const currentBoard = useOptionalBoard();
   const [isOpen, setIsOpen] = useState(false);
   const [search, setSearch] = useState("");
@@ -50,20 +53,27 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
     data: boards = [],
     isPending,
     isError,
-  } = clientApi.board.getManageOverview.useQuery(undefined, {
+  } = clientApi.board.getManageOverview.useQuery(
-    enabled: isOpen,
+    { fullPreview: true },
-  });
+    {
+      enabled: isOpen,
+    },
+  );
 
-  const availableBoards = useMemo(
+  const switcherBoards = useMemo(
-    () => boards.filter((board) => board.id !== currentBoard?.id),
+    () => [
+      ...boards.filter((board) => board.id !== currentBoard?.id),
+      ...boards.filter((board) => board.id === currentBoard?.id),
+    ],
     [boards, currentBoard?.id],
   );
   const filteredBoards = useMemo(() => {
     const normalizedSearch = search.trim().toLocaleLowerCase();
-    if (normalizedSearch.length === 0) return availableBoards;
+    if (normalizedSearch.length === 0) return switcherBoards;
-    return availableBoards.filter((board) => board.name.toLocaleLowerCase().includes(normalizedSearch));
+    return switcherBoards.filter((board) => board.name.toLocaleLowerCase().includes(normalizedSearch));
-  }, [availableBoards, search]);
+  }, [search, switcherBoards]);
   const columnCount = Math.max(1, Math.min(filteredBoards.length, responsiveColumnCount));
+  const modalColumnCount = Math.max(1, Math.min(switcherBoards.length, responsiveColumnCount));
 
   const openSwitcher = useCallback(() => {
     setIsOpen(true);
@@ -73,7 +83,7 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
     setSearch("");
     setActiveIndex(0);
   }, []);
-  const preloadBoards = () => void utils.board.getManageOverview.prefetch();
+  const preloadBoards = () => void utils.board.getManageOverview.prefetch({ fullPreview: true });
 
   useHotkeys([[boardSwitcherHotkey, openSwitcher, { preventDefault: true }]]);
 
@@ -88,14 +98,17 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
   }, [activeIndex, filteredBoards.length, isOpen]);
 
   const handleModalKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
-    if (event.key === "Backspace") {
+    const isSearchInput =
+      event.target instanceof HTMLInputElement && event.target.dataset.boardSwitcherSearch !== undefined;
+
+    if (!isSearchInput && event.key === "Backspace") {
       event.preventDefault();
       setSearch((current) => current.slice(0, -1));
       setActiveIndex(0);
       return;
     }
 
-    if (event.key.length === 1 && !event.altKey && !event.ctrlKey && !event.metaKey) {
+    if (!isSearchInput && event.key.length === 1 && !event.altKey && !event.ctrlKey && !event.metaKey) {
       event.preventDefault();
       setSearch((current) => `${current}${event.key}`);
       setActiveIndex(0);
@@ -141,7 +154,7 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
   };
 
   const results = getBoardSwitcherResults({
-    availableBoardCount: availableBoards.length,
+    availableBoardCount: switcherBoards.length,
     filteredBoards,
     isError,
     isPending,
@@ -152,6 +165,7 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
     setActiveIndex,
     optionRefs,
     columnCount,
+    manageBoardsT,
   });
 
   return (
@@ -161,54 +175,40 @@ export const BoardSwitcher = ({ children }: BoardSwitcherProps) => {
       <Modal
         opened={isOpen}
         onClose={closeSwitcher}
-        title={
+        withCloseButton={false}
-          <Group gap="sm" wrap="nowrap">
+        yOffset="15vh"
-            <ThemeIcon variant="light" radius="md">
+        aria-label={t("title")}
-              <IconReplace size={18} stroke={1.5} />
+        size={`${modalColumnCount * 15 + Math.max(0, modalColumnCount - 1) * 0.75}rem`}
-            </ThemeIcon>
+        overlayProps={{ backgroundOpacity: 0, blur: 2 }}
-            <Text fw={700}>{t("title")}</Text>
-          </Group>
-        }
-        size={1280}
-        yOffset={32}
-        overlayProps={{ backgroundOpacity: 0.18, blur: 2 }}
         transitionProps={{ transition: "fade", duration: 100, timingFunction: "ease" }}
+        classNames={{ content: classes.modalContent, body: classes.modalBody }}
       >
         <Stack
-          data-autofocus
           tabIndex={-1}
-          gap="md"
+          gap="xs"
           onKeyDown={handleModalKeyDown}
           className={classes.content}
           aria-describedby="board-switcher-instructions"
         >
           <VisuallyHidden id="board-switcher-instructions">{t("keyboard.instructions")}</VisuallyHidden>
-          <ScrollArea.Autosize mah={640} type="auto" offsetScrollbars>
+          <TextInput
+            data-autofocus
+            data-board-switcher-search
+            value={search}
+            onChange={(event) => {
+              setSearch(event.currentTarget.value);
+              setActiveIndex(0);
+            }}
+            leftSection={<IconSearch size="1rem" stroke={1.6} />}
+            placeholder={t("title")}
+            aria-label={t("title")}
+            aria-controls="board-switcher-results"
+            radius="xl"
+            classNames={{ input: classes.searchInput }}
+          />
+          <ScrollArea.Autosize mah="min(80vh, 42rem)" type="never">
             {results}
           </ScrollArea.Autosize>
-
-          <Group justify={currentBoard ? "space-between" : "flex-end"} gap="xs" visibleFrom="sm">
-            {currentBoard && (
-              <Text size="xs" c="dimmed">
-                {t("currentHidden", { name: currentBoard.name })}
-              </Text>
-            )}
-            <Group gap="xs">
-              <Kbd size="xs">
-                <IconArrowRight size={12} />
-              </Kbd>
-              <Kbd size="xs">
-                <IconArrowDown size={12} />
-              </Kbd>
-              <Text size="xs" c="dimmed">
-                {t("keyboard.navigate")}
-              </Text>
-              <Kbd size="xs">Enter</Kbd>
-              <Text size="xs" c="dimmed">
-                {t("keyboard.open")}
-              </Text>
-            </Group>
-          </Group>
         </Stack>
       </Modal>
     </>
@@ -227,6 +227,7 @@ interface BoardSwitcherResultsProps {
   setActiveIndex: (index: number) => void;
   optionRefs: RefObject<Array<HTMLAnchorElement | null>>;
   columnCount: number;
+  manageBoardsT: ReturnType<typeof useI18n<"management.page.board">>;
 }
 
 const getBoardSwitcherResults = ({
@@ -241,6 +242,7 @@ const getBoardSwitcherResults = ({
   setActiveIndex,
   optionRefs,
   columnCount,
+  manageBoardsT,
 }: BoardSwitcherResultsProps) => {
   if (isPending) {
     return (
@@ -287,7 +289,7 @@ const getBoardSwitcherResults = ({
   }
 
   return (
-    <SimpleGrid id="board-switcher-results" aria-label={t("results")} cols={columnCount} spacing="md" p={4}>
+    <SimpleGrid id="board-switcher-results" aria-label={t("results")} cols={columnCount} spacing="xs" p={2}>
       {filteredBoards.map((board, index) => (
         <UnstyledButton
           key={board.id}
@@ -296,7 +298,7 @@ const getBoardSwitcherResults = ({
           }}
           className={classes.option}
           w="100%"
-          maw={320}
+          maw={240}
           mx="auto"
           component={Link}
           href={`/boards/${encodeURIComponent(board.name)}`}
@@ -306,21 +308,50 @@ const getBoardSwitcherResults = ({
           onFocus={() => setActiveIndex(index)}
           onPointerEnter={() => setActiveIndex(index)}
         >
-          <Card padding={0} withBorder radius="md" className={classes.card}>
+          <Card padding={0} withBorder radius="lg" className={classes.card}>
             <Card.Section>
               <BoardLayoutThumbnail
                 preview={board.preview}
                 label={t("preview", { name: board.name, count: String(board.preview?.items.length ?? 0) })}
+                fitFullLayout
               />
             </Card.Section>
-            <Card.Section withBorder p="sm">
+            <Card.Section withBorder px="sm" py={6}>
-              <Group gap="sm" wrap="nowrap">
+              <Group justify="space-between" gap="xs" wrap="nowrap">
-                <ThemeIcon variant="light" radius="md" size="md">
+                <Text fw={600} size="sm" truncate>
-                  <IconLayoutBoard size={16} stroke={1.5} />
-                </ThemeIcon>
-                <Text fw={650} truncate>
                   {board.name}
                 </Text>
+                <Group gap={4} wrap="nowrap">
+                  {board.isHome && (
+                    <Tooltip label={manageBoardsT("action.setHomeBoard.badge.tooltip")}>
+                      <Badge
+                        className={classes.metadataBadge}
+                        color="yellow"
+                        variant="light"
+                        aria-label={manageBoardsT("action.setHomeBoard.badge.label")}
+                      >
+                        <IconHomeFilled size="0.7rem" />
+                      </Badge>
+                    </Tooltip>
+                  )}
+                  {board.isMobileHome && (
+                    <Tooltip label={manageBoardsT("action.setMobileHomeBoard.badge.tooltip")}>
+                      <Badge
+                        className={classes.metadataBadge}
+                        color="yellow"
+                        variant="light"
+                        aria-label={manageBoardsT("action.setMobileHomeBoard.badge.label")}
+                      >
+                        <IconDeviceMobile size="0.7rem" />
+                      </Badge>
+                    </Tooltip>
+                  )}
+                  {board.creator && (
+                    <Tooltip label={board.creator.name ?? manageBoardsT("preview.unknownCreator")}>
+                      <UserAvatar user={board.creator} size="xs" />
+                    </Tooltip>
+                  )}
+                </Group>
               </Group>
             </Card.Section>
           </Card>

apps/nextjs/src/components/board/items/item-content.module.css

@@ -1,16 +1,3 @@
-.badge {
-  @mixin dark {
-    --background-color: rgb(from var(--mantine-color-dark-6) r g b / var(--opacity));
-    --border-color: rgb(from var(--mantine-color-dark-4) r g b / var(--opacity));
-  }
-  @mixin light {
-    --background-color: rgb(from var(--mantine-color-white) r g b / var(--opacity));
-    --border-color: rgb(from var(--mantine-color-gray-3) r g b / var(--opacity));
-  }
-  background-color: var(--background-color) !important;
-  border-color: var(--border-color) !important;
-}
-
 .settingsButton {
   opacity: 0;
   pointer-events: none;

apps/nextjs/src/components/board/items/item-content.tsx

@@ -1,9 +1,8 @@
-import type { ComponentType, CSSProperties, MutableRefObject } from "react";
+import type { ComponentType, CSSProperties, MutableRefObject, PropsWithChildren } from "react";
 import { memo, Suspense, use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import dynamic from "next/dynamic";
-import type { CardProps } from "@mantine/core";
+import { Box, Button, Center, Loader, Portal } from "@mantine/core";
-import { Badge, Box, Button, Card, Center, Loader, Portal } from "@mantine/core";
 import { useElementSize, useIsomorphicEffect } from "@mantine/hooks";
 import { QueryErrorResetBoundary, useQueryClient } from "@tanstack/react-query";
 import combineClasses from "clsx";
@@ -24,9 +23,11 @@ import {
 } from "@homarr/widgets/definition";
 import type { WidgetComponentProps, WidgetDefinition, WidgetRuntimeRef } from "@homarr/widgets/definition";
 import { loadWidgetResources, reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";
+import { WidgetCardShell, WidgetTitleBadge } from "@homarr/widgets/widget-card-shell";
 
 import type { SectionItem } from "~/app/[locale]/boards/_types";
 import { getLogicalTrackSize } from "~/components/board/layout";
+import { useBoardCanvasScale } from "~/components/board/layout/scaled-board-canvas";
 import advancedFocusClasses from "../advanced-focus/advanced-focus.module.css";
 import { useAdvancedFocus } from "../advanced-focus/context";
 import { startAdvancedFocusEntrance } from "../advanced-focus/entrance";
@@ -34,7 +35,6 @@ import { getAdvancedFocusClosePosition, getAdvancedFocusRect } from "../advanced
 import { AdvancedFocusManualSurface } from "../advanced-focus/manual-surface";
 import { redirectShiftWheel } from "../advanced-focus/wheel";
 import { useBoardGridPortalHost } from "../sections/grid/grid-portal-host";
-import classes from "../sections/item.module.css";
 import { useItemActions } from "./item-actions";
 import itemContentClasses from "./item-content.module.css";
 import { WidgetContextMenu } from "./widget-context-menu";
@@ -48,47 +48,28 @@ interface BoardItemContentProps {
   item: SectionItem;
 }
 
-const getOverflowFromKind = (kind: SectionItem["kind"], hasCustomCssClasses: boolean) => {
+type BoardItemCardProps = PropsWithChildren<{
-  if (kind === "systemResources") return { overflowX: "visible", overflowY: "visible" } as const;
-  if (kind === "iframe" || kind === "assistant") return { overflowX: "hidden", overflowY: "hidden" } as const;
-  if (hasCustomCssClasses) return {};
-  return { overflowX: "hidden", overflowY: "auto" } as const;
-};
-
-type BoardItemCardProps = CardProps & {
   item: SectionItem;
   innerRef: (element: HTMLDivElement | null) => void;
-};
+}>;
 
-const BoardItemCard = ({ item, innerRef, children, ...cardProps }: BoardItemCardProps) => {
+const BoardItemCard = ({ item, innerRef, children }: BoardItemCardProps) => {
   const board = useRequiredBoard();
 
   return (
-    <Card
+    <WidgetCardShell
-      {...cardProps}
+      innerRef={innerRef}
-      ref={innerRef}
+      kind={item.kind}
+      advancedOptions={item.advancedOptions}
+      opacity={board.opacity / 100}
       w="100%"
       h="100%"
       data-grid-item-content
-      className={combineClasses(
-        classes.itemCard,
-        `${item.kind}-wrapper`,
-        "board-grid-item-content",
-        item.advancedOptions.customCssClasses.join(" "),
-      )}
       radius={board.itemRadius}
-      styles={{
-        root: {
-          "--opacity": board.opacity / 100,
-          containerType: "size",
-          ...getOverflowFromKind(item.kind, item.advancedOptions.customCssClasses.length > 0),
-          "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-        },
-      }}
       p={0}
     >
       {children}
-    </Card>
+    </WidgetCardShell>
   );
 };
 
@@ -167,6 +148,7 @@ const LoadedBoardItemContent = ({
   const cardRef = useRef<HTMLDivElement>(null);
   const previewEntranceFrameRef = useRef<number | null>(null);
   const board = useRequiredBoard();
+  const boardCanvasScale = useBoardCanvasScale();
   const t = useI18n();
   const [isEditMode] = useEditMode();
   const settings = useSettings();
@@ -180,6 +162,10 @@ const LoadedBoardItemContent = ({
   const { width: viewportWidth, height: viewportHeight } = viewportSize;
   const supportsAdvancedFocus = definitionSupportsAdvancedFocus(definition);
   const widgetName = getWidgetName(item.kind, t);
+  const previewDimensions = useMemo(
+    () => ({ width, height, scale: boardCanvasScale }),
+    [boardCanvasScale, height, width],
+  );
   const advancedViewLabel = t("item.advancedFocus.label", { widget: widgetName });
   const advancedViewId = `advanced-focus-${item.id}`;
   const activeFocus = supportsAdvancedFocus && active?.itemId === item.id ? active : null;
@@ -291,8 +277,11 @@ const LoadedBoardItemContent = ({
       : undefined;
 
   const widgetCard = (
-    <Card
+    <WidgetCardShell
-      ref={cardRef}
+      innerRef={cardRef}
+      kind={item.kind}
+      advancedOptions={item.advancedOptions}
+      opacity={isAdvanced ? 0.98 : board.opacity / 100}
       id={isPreview ? advancedViewId : undefined}
       role={isPreview ? "region" : undefined}
       aria-label={isPreview ? advancedViewLabel : undefined}
@@ -303,21 +292,9 @@ const LoadedBoardItemContent = ({
       h={isManual ? "100%" : isAdvanced ? undefined : "100%"}
       w={isManual ? "100%" : isAdvanced ? undefined : "100%"}
       className={combineClasses(
-        classes.itemCard,
-        `${item.kind}-wrapper`,
-        "board-grid-item-content",
         isPreview && advancedFocusClasses.surface,
         activeFocus?.phase === "closing" && isPreview && advancedFocusClasses.surfaceClosing,
-        item.advancedOptions.customCssClasses.join(" "),
       )}
-      styles={{
-        root: {
-          "--opacity": isAdvanced ? 0.98 : board.opacity / 100,
-          containerType: "size",
-          ...getOverflowFromKind(item.kind, item.advancedOptions.customCssClasses.length > 0),
-          "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-        },
-      }}
       style={previewStyle}
     >
       <Box ref={contentRef} w="100%" h="100%" mih={0}>
@@ -345,15 +322,16 @@ const LoadedBoardItemContent = ({
           />
         </ErrorBoundary>
       </Box>
-    </Card>
+    </WidgetCardShell>
   );
 
   return (
     <>
-      {isEditMode && <BoardItemMenu item={menuItem} definition={definition} />}
+      {isEditMode && <BoardItemMenu item={menuItem} definition={definition} previewDimensions={previewDimensions} />}
       <WidgetContextMenu
         item={item}
         definition={definition}
+        previewDimensions={previewDimensions}
         widgetStateRef={widgetStateRef}
         widgetRuntimeRef={widgetRuntimeRef}
         sourceRef={sourceRef}
@@ -418,25 +396,12 @@ const LoadedBoardItemContent = ({
           )}
         </Box>
       </WidgetContextMenu>
-      {!isAdvanced && item.advancedOptions.title?.trim() && (
+      {!isAdvanced && (
-        <Badge
+        <WidgetTitleBadge
-          pos="absolute"
+          advancedOptions={item.advancedOptions}
-          style={{ zIndex: "var(--mantine-z-index-app)" }}
+          opacity={board.opacity / 100}
-          top={2}
-          left={16}
-          size="xs"
           radius={board.itemRadius}
-          styles={{
+        />
-            root: {
-              "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-              "--opacity": board.opacity / 100,
-            },
-          }}
-          className={itemContentClasses.badge}
-          c="var(--mantine-color-text)"
-        >
-          {item.advancedOptions.title}
-        </Badge>
       )}
     </>
   );

apps/nextjs/src/components/board/items/item-menu.tsx

@@ -21,6 +21,7 @@ import { LazyWidgetEditModal, preloadWidgetEditModal } from "./lazy-widget-edit-
 interface BoardItemMenuProps {
   item: SectionItem;
   definition: WidgetDefinition;
+  previewDimensions: { width: number; height: number; scale?: number };
   resetErrorBoundary?: () => void;
 }
 
@@ -31,7 +32,7 @@ export const BoardItemMenu = (props: BoardItemMenuProps) => {
 
   return <BoardItemMenuInner {...props} />;
 };
-const BoardItemMenuInner = ({ item, definition, resetErrorBoundary }: BoardItemMenuProps) => {
+const BoardItemMenuInner = ({ item, definition, previewDimensions, resetErrorBoundary }: BoardItemMenuProps) => {
   const { data: session } = useSession();
   const canDuplicate = item.kind !== "customApi" || (session?.user.permissions.includes("admin") ?? false);
   const refResetErrorBoundaryOnNextRender = useRef(false);
@@ -89,6 +90,7 @@ const BoardItemMenuInner = ({ item, definition, resetErrorBoundary }: BoardItemM
         integrationSupport: "supportedIntegrations" in definition,
         settings,
         itemId: item.id,
+        previewDimensions,
         appId: item.kind === "app" ? (item.options.appId as string | undefined) : undefined,
       },
       {

apps/nextjs/src/components/board/items/item-select-modal.tsx

@@ -30,6 +30,7 @@ import {
   getIntegrationName,
   getWidgetName,
   getRootSectionLane,
+  widgetDefaultSizes,
   widgetIntegrationSupport,
   widgetKinds,
   widgetKindsWithOptionalIntegrations,
@@ -47,6 +48,7 @@ import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr
 import type { EmptySection } from "~/app/[locale]/boards/_types";
 import { useSetupAnalytics } from "~/components/create/setup-analytics";
 import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
+import { getSectionGridColumnCount } from "../sections/grid/section-grid-placements";
 import { useItemActions } from "./item-actions";
 import type { WidgetConnectionStatus } from "./item-select-data";
 import {
@@ -76,6 +78,8 @@ export interface WidgetItemData {
 }
 
 const selectGridCols = { base: 1, xs: 2, sm: 2, md: 3, lg: 4 };
+const defaultWidgetSize = { width: 1, height: 1 };
+const maximumWidgetHeight = 64;
 
 const ItemSelectModalContent = ({
   actions,
@@ -124,6 +128,13 @@ const ItemSelectModalContent = ({
   const effectiveSectionId = placementOptions.some(({ value }) => value === targetSectionId)
     ? targetSectionId
     : (placementOptions[0]?.value ?? null);
+  const maximumWidgetSize = useMemo(() => {
+    if (!effectiveSectionId) return defaultWidgetSize;
+    return {
+      width: Math.max(1, getSectionGridColumnCount(board, currentLayoutId, effectiveSectionId) ?? 1),
+      height: maximumWidgetHeight,
+    };
+  }, [board, currentLayoutId, effectiveSectionId]);
 
   const [loadingSelection, setLoadingSelection] = useState<string | null>(null);
   const selectionLock = useRef(false);
@@ -246,6 +257,7 @@ const ItemSelectModalContent = ({
     try {
       const definition = await loadWidgetDefinition("customApi");
       const itemId = createId();
+      const initialSize = widgetDefaultSizes.customApi ?? defaultWidgetSize;
       const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
       const options = {
         ...defaultOptions,
@@ -263,7 +275,7 @@ const ItemSelectModalContent = ({
             options,
             integrationIds: [],
           },
-          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }) => {
+          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }, selectedSize) => {
             const updatedBoard = createItem({
               id: itemId,
               kind: "customApi",
@@ -271,12 +283,14 @@ const ItemSelectModalContent = ({
               options: configuredOptions,
               targetSectionId: effectiveSectionId ?? undefined,
               advancedOptions,
+              size: selectedSize ?? initialSize,
             });
             notifyCreated(updatedBoard, itemId, customWidgetDefinition.name);
           },
           integrationData: [],
           integrationSupport: false,
           settings,
+          previewResize: { initialSize, maximumSize: maximumWidgetSize },
         },
         {
           title: (titleT) => `${titleT("item.edit.title")} - ${customWidgetDefinition.name}`,
@@ -311,6 +325,7 @@ const ItemSelectModalContent = ({
       const matchingIntegrationCount = Math.min(matchingIntegrations.length, maxIntegrations);
       const itemId = createId();
       const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
+      const initialSize = widgetDefaultSizes[kind] ?? defaultWidgetSize;
       const openEditor = (
         availableIntegrations: { id: string; name: string; url: string; kind: IntegrationKind }[],
       ) => {
@@ -326,7 +341,7 @@ const ItemSelectModalContent = ({
               options: defaultOptions,
               integrationIds: selectedIntegrationIds,
             },
-            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
+            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }, selectedSize) => {
               const updatedBoard = createItem({
                 id: itemId,
                 kind,
@@ -334,6 +349,7 @@ const ItemSelectModalContent = ({
                 integrationIds: newIntegrationIds,
                 targetSectionId: effectiveSectionId ?? undefined,
                 advancedOptions,
+                size: selectedSize ?? initialSize,
               });
               if (!notifyCreated(updatedBoard, itemId, getWidgetName(kind, t))) return;
               trackSetup("widget-completed", {
@@ -346,6 +362,7 @@ const ItemSelectModalContent = ({
             integrationData: availableIntegrations,
             integrationSupport: hasIntegrationSupport,
             settings,
+            previewResize: { initialSize, maximumSize: maximumWidgetSize },
           },
           {
             title: (titleT) => `${titleT("item.edit.title")} - ${getWidgetName(kind, titleT)}`,

apps/nextjs/src/components/board/items/lazy-widget-edit-modal.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import type { PropsWithChildren } from "react";
 import { Suspense, use, useCallback, useMemo, useState } from "react";
 import { Center, Loader } from "@mantine/core";
 import { ErrorBoundary } from "react-error-boundary";
@@ -7,16 +8,49 @@ import type { FallbackProps } from "react-error-boundary";
 
 import { clientApi } from "@homarr/api/client";
 import type { WidgetKind } from "@homarr/definitions";
-import { createModal, modalSizeForm, useModalAction } from "@homarr/modals";
+import { widgetDefaultSizes } from "@homarr/definitions";
+import { createModal, useModalAction } from "@homarr/modals";
 import { WidgetError } from "@homarr/widgets/errors";
 import type * as WidgetModalsModule from "@homarr/widgets/modals";
-import type { WidgetEditModalProps } from "@homarr/widgets/modals";
+import type { WidgetEditModalProps, WidgetEditModalSize } from "@homarr/widgets/modals";
+import { loadWidgetComponent } from "@homarr/widgets/manifest";
 import type { IntegrationSelectOption } from "@homarr/widgets/widget-integration-select";
 
+import { AssistantContext, useOptionalHomarrAssistant } from "~/components/assistant/assistant-context";
+import { getLogicalTrackSize } from "~/components/board/layout";
 import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
 import type * as IntegrationEditFormModule from "~/components/integration/embedded-integration-edit-form";
 import type { EmbeddedIntegrationEditFormProps } from "~/components/integration/embedded-integration-edit-form";
 
+const defaultWidgetSize = { width: 1, height: 1 };
+const ignoreAssistantAction = () => undefined;
+const ignoreAssistantPrompt = () => false;
+const ignoreAssistantRefresh = () => Promise.resolve();
+const getPreviewDimensions = (size: WidgetEditModalSize) => ({
+  width: getLogicalTrackSize(size.width),
+  height: getLogicalTrackSize(size.height),
+});
+
+const PreviewRuntimeWrapper = ({ children }: PropsWithChildren) => {
+  const assistant = useOptionalHomarrAssistant();
+  const previewAssistant = useMemo(() => {
+    if (!assistant) return null;
+    return {
+      ...assistant,
+      open: ignoreAssistantAction,
+      close: ignoreAssistantAction,
+      toggle: ignoreAssistantAction,
+      sendPrompt: ignoreAssistantPrompt,
+      refreshCurrentView: ignoreAssistantRefresh,
+      setWidgetVisible: ignoreAssistantAction,
+      activateWidget: ignoreAssistantAction,
+    };
+  }, [assistant]);
+
+  if (!previewAssistant) return children;
+  return <AssistantContext.Provider value={previewAssistant}>{children}</AssistantContext.Provider>;
+};
+
 let widgetEditModalPromise: Promise<typeof WidgetModalsModule> | undefined;
 
 export const loadWidgetEditModal = () => {
@@ -83,6 +117,7 @@ interface LazyWidgetEditModalContentProps {
 
 const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
   const { WidgetEditModal } = use(loadWidgetEditModal());
+  const { default: PreviewComponent } = use(loadWidgetComponent(props.innerProps.kind));
   const { openModal: openIntegrationModal } = useModalAction(IntegrationSelectModal);
   const Component = WidgetEditModal.component;
   const utils = clientApi.useUtils();
@@ -114,6 +149,18 @@ const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
     const additional = createdIntegrations.filter((c) => !existing.some((e) => e.id === c.id));
     return [...existing, ...additional];
   }, [props.innerProps.integrationData, createdIntegrations]);
+  const previewDimensions = useMemo(() => {
+    if (props.innerProps.previewDimensions) return props.innerProps.previewDimensions;
+    const size = widgetDefaultSizes[props.innerProps.kind] ?? defaultWidgetSize;
+    return {
+      width: getLogicalTrackSize(size.width),
+      height: getLogicalTrackSize(size.height),
+    };
+  }, [props.innerProps.kind, props.innerProps.previewDimensions]);
+  let previewResize = props.innerProps.previewResize;
+  if (previewResize) {
+    previewResize = { ...previewResize, getDimensions: getPreviewDimensions };
+  }
 
   return (
     <Component
@@ -122,6 +169,10 @@ const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
         ...props.innerProps,
         integrationData: combinedIntegrationData,
         integrationEditForm: LazyIntegrationEditForm,
+        previewComponent: PreviewComponent,
+        previewDimensions,
+        previewResize,
+        previewWrapper: PreviewRuntimeWrapper,
         onOpenNewIntegration: supportedKinds.length > 0 ? handleOpenNewIntegration : undefined,
       }}
     />
@@ -157,6 +208,10 @@ export const LazyWidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>
   defaultTitle(t) {
     return t("item.edit.title");
   },
-  size: modalSizeForm,
+  size: "100rem",
+  transitionProps: {
+    transition: "pop",
+    duration: 180,
+  },
   closeOnClickOutside: false,
 });

apps/nextjs/src/components/board/items/widget-context-menu.tsx

@@ -35,6 +35,7 @@ import { matchesWidgetItemQuery } from "./widget-query-scope";
 interface WidgetContextMenuProps {
   item: SectionItem;
   definition: WidgetDefinition;
+  previewDimensions: { width: number; height: number; scale?: number };
   widgetStateRef: MutableRefObject<Record<string, unknown> | null>;
   widgetRuntimeRef: WidgetRuntimeRef;
   sourceRef: RefObject<HTMLElement | null>;
@@ -44,6 +45,7 @@ interface WidgetContextMenuProps {
 export const WidgetContextMenu = ({
   item,
   definition,
+  previewDimensions,
   widgetRuntimeRef,
   sourceRef,
   children,
@@ -160,7 +162,7 @@ export const WidgetContextMenu = ({
         definition,
         value: {
           advancedOptions: item.advancedOptions,
-          options: item.options,
+          options,
           integrationIds: item.integrationIds,
         },
         onSuccessfulEdit: (editResult) => {
@@ -189,6 +191,9 @@ export const WidgetContextMenu = ({
         ),
         integrationSupport: definition.supportedIntegrations !== undefined,
         settings,
+        itemId: item.id,
+        boardId: board.id,
+        previewDimensions,
         appId: item.kind === "app" ? (item.options.appId as string | undefined) : undefined,
       },
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -197,12 +202,15 @@ export const WidgetContextMenu = ({
       },
     );
   }, [
+    board.id,
     definition,
     integrationData,
     item,
     handleRefetch,
     openModal,
+    options,
     persistBoard,
+    previewDimensions,
     settings,
     updateItemAdvancedOptions,
     updateItemIntegrations,

apps/nextjs/src/components/board/layout/README.md

@@ -2,17 +2,16 @@
 
 The board uses fixed logical units:
 
-- one `1 × 1` item is exactly `200 × 200` logical pixels;
+- one grid track has a `212 × 212` logical-pixel footprint;
-- the gap matches Mantine's `sm` spacing at `12` logical pixels, giving a `212` pixel track pitch;
+- cards are inset by `10` visual pixels on every side, matching the legacy GridStack gutter;
-- multi-cell items include the gaps between their cells (`2 × 1` is `412 × 200`);
+- multi-cell items occupy complete track footprints (`2 × 1` is `424 × 212` before the card inset);
 - the canvas is zoomed once with one uniform scale derived from its available width.
 
-Items keep the same logical dimensions at every viewport. The viewport reserves
+Grid footprints keep the same logical dimensions at every viewport. Widget cards
-the painted size while the inner canvas remains at its logical dimensions, so a
+use a scale-compensated inset so their painted size and content measurements
-widget's `clientWidth`, `clientHeight`, and `ResizeObserver` measurements stay
+match the legacy responsive grid. The visual canvas always fits the available
-stable. The visual canvas always fits the available width, every root lane
+width, every root lane keeps at least one viewport of height, and edit-mode
-keeps at least one viewport of height, and edit-mode previews extend it downward
+previews extend it downward as needed.
-as needed.
 
 The read-only renderer should:
 

apps/nextjs/src/components/board/layout/board-lanes.ts

@@ -2,7 +2,7 @@ import type { BoardLane } from "@homarr/definitions";
 import { getBoardLaneColumnCount, getRootSectionLane } from "@homarr/definitions";
 
 import type { Board, EmptySection } from "~/app/[locale]/boards/_types";
-import { getLogicalTrackSize, getLayoutRowCount, normalizeGridPlacement } from "./geometry";
+import { getLogicalGridSize, getLayoutRowCount, normalizeGridPlacement } from "./geometry";
 import { getCollapsedDisplayLayout } from "./reflow";
 import type { GridPlacement } from "./types";
 
@@ -90,5 +90,5 @@ export const getInitialBoardLogicalHeight = (board: Board, layoutId: string) =>
     return [getLayoutRowCount(displayPlacements)];
   });
 
-  return getLogicalTrackSize(Math.max(0, ...rowCounts));
+  return getLogicalGridSize(Math.max(0, ...rowCounts));
 };

apps/nextjs/src/components/board/layout/geometry.ts

@@ -10,12 +10,23 @@ export const getLogicalTrackSize = (trackCount: number) => {
   return normalizedTrackCount * LOGICAL_GRID_CELL_SIZE + (normalizedTrackCount - 1) * LOGICAL_GRID_GAP;
 };
 
+/**
+ * Returns the complete footprint occupied by grid tracks. Cards are inset
+ * inside this footprint so their visual gutters stay fixed while the canvas
+ * is scaled.
+ */
+export const getLogicalGridSize = (trackCount: number) => {
+  const normalizedTrackCount = Math.max(0, toFiniteNumber(trackCount, "trackCount"));
+
+  return normalizedTrackCount * LOGICAL_GRID_PITCH;
+};
+
 export const getLogicalItemStyle = ({ x, y, w, h }: GridCoordinates): CSSProperties => ({
   position: "absolute",
   left: x * LOGICAL_GRID_PITCH,
   top: y * LOGICAL_GRID_PITCH,
-  width: getLogicalTrackSize(w),
+  width: getLogicalGridSize(w),
-  height: getLogicalTrackSize(h),
+  height: getLogicalGridSize(h),
 });
 
 export const getLayoutRowCount = (placements: readonly GridCoordinates[]) =>
@@ -25,7 +36,7 @@ export const getGridRowCountForVisualHeight = (visualHeight: number, visualScale
   if (!Number.isFinite(visualHeight) || visualHeight <= 0) return 1;
   if (!Number.isFinite(visualScale) || visualScale <= 0) return 1;
 
-  return Math.max(1, Math.ceil((visualHeight / visualScale + LOGICAL_GRID_GAP) / LOGICAL_GRID_PITCH));
+  return Math.max(1, Math.ceil(visualHeight / visualScale / LOGICAL_GRID_PITCH));
 };
 
 export const normalizeGridPlacement = <TPlacement extends GridPlacement>(

apps/nextjs/src/components/board/layout/test/board-lanes.spec.ts

@@ -8,7 +8,7 @@ import { ItemMockBuilder } from "~/components/board/items/actions/test/mocks/ite
 import {
   getBoardLaneColumnCount,
   getInitialBoardLogicalHeight,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   getRootSectionForLane,
 } from "../index";
 
@@ -131,6 +131,6 @@ describe("board lanes", () => {
       },
     ];
 
-    expect(getInitialBoardLogicalHeight(board, layoutId)).toBe(getLogicalTrackSize(4));
+    expect(getInitialBoardLogicalHeight(board, layoutId)).toBe(getLogicalGridSize(4));
   });
 });

apps/nextjs/src/components/board/layout/test/geometry.spec.ts

@@ -3,24 +3,28 @@ import { describe, expect, test } from "vitest";
 import {
   getGridRowCountForVisualHeight,
   getLayoutRowCount,
+  getLogicalGridSize,
   getLogicalItemStyle,
   getLogicalTrackSize,
   normalizeGridPlacement,
 } from "../index";
 
 describe("fixed dashboard geometry", () => {
-  test("keeps a 1x1 item exactly 200px with a fixed 12px gap", () => {
+  test("separates content track sizes from complete grid footprints", () => {
     expect(getLogicalTrackSize(1)).toBe(200);
     expect(getLogicalTrackSize(0.5)).toBe(94);
     expect(getLogicalTrackSize(2)).toBe(412);
     expect(getLogicalTrackSize(3)).toBe(624);
+    expect(getLogicalGridSize(1)).toBe(212);
+    expect(getLogicalGridSize(2)).toBe(424);
+    expect(getLogicalGridSize(3)).toBe(636);
 
     expect(getLogicalItemStyle({ x: 1, y: 2, w: 2, h: 3 })).toEqual({
       position: "absolute",
       left: 212,
       top: 424,
-      width: 412,
+      width: 424,
-      height: 624,
+      height: 636,
     });
   });
 

apps/nextjs/src/components/board/sections/grid/dnd/coordinates.ts

@@ -1,4 +1,4 @@
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import type { GridPlacement } from "~/components/board/layout";
 import type { GridResizeDirection } from "./types";
 
@@ -38,7 +38,7 @@ export const getSnappedGridCoordinates = ({
   target: RectangleLike;
   columnCount: number;
 }) => {
-  const logicalWidth = getLogicalTrackSize(columnCount);
+  const logicalWidth = getLogicalGridSize(columnCount);
   const visualScale = logicalWidth > 0 ? target.width / logicalWidth : 0;
   if (!Number.isFinite(visualScale) || visualScale <= 0) return null;
 

apps/nextjs/src/components/board/sections/grid/grid-editor.tsx

@@ -39,7 +39,7 @@ import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
 import { getWidgetName } from "@homarr/definitions";
 import { useI18n } from "@homarr/translation/client";
 
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import {
   beginGridTransaction,
   cancelGridTransaction,
@@ -792,8 +792,8 @@ export default function GridEditor({
       data-grid-depth={depth}
       style={
         {
-          width: getLogicalTrackSize(columnCount),
+          width: getLogicalGridSize(columnCount),
-          height: getLogicalTrackSize(rowCount),
+          height: getLogicalGridSize(rowCount),
           "--board-grid-pitch": `${LOGICAL_GRID_PITCH}px`,
         } as CSSProperties
       }
@@ -1234,8 +1234,8 @@ const getEntryVisualScale = (element: HTMLElement | null, placement: SectionGrid
   if (!element) return null;
   const rectangle = element.getBoundingClientRect();
   const scale = {
-    x: rectangle.width / getLogicalTrackSize(placement.w),
+    x: rectangle.width / getLogicalGridSize(placement.w),
-    y: rectangle.height / getLogicalTrackSize(placement.h),
+    y: rectangle.height / getLogicalGridSize(placement.h),
   };
   return Number.isFinite(scale.x) && scale.x > 0 && Number.isFinite(scale.y) && scale.y > 0 ? scale : null;
 };

apps/nextjs/src/components/board/sections/grid/grid-preview-geometry.ts

@@ -1,4 +1,4 @@
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import type { GridPlacement } from "~/components/board/layout";
 
 export interface GridPreviewDomState {
@@ -75,8 +75,8 @@ export const clearGridPreviewGeometry = (
 const applyPreviewGeometry = (element: HTMLElement, controlled: GridPlacement, preview: GridPlacement) => {
   element.style.setProperty("--board-grid-preview-x", `${(preview.x - controlled.x) * LOGICAL_GRID_PITCH}px`);
   element.style.setProperty("--board-grid-preview-y", `${(preview.y - controlled.y) * LOGICAL_GRID_PITCH}px`);
-  element.style.setProperty("--board-grid-preview-width", `${getLogicalTrackSize(preview.w)}px`);
+  element.style.setProperty("--board-grid-preview-width", `${getLogicalGridSize(preview.w)}px`);
-  element.style.setProperty("--board-grid-preview-height", `${getLogicalTrackSize(preview.h)}px`);
+  element.style.setProperty("--board-grid-preview-height", `${getLogicalGridSize(preview.h)}px`);
   element.setAttribute("data-grid-preview", "true");
   setPlacementAttributes(element, preview);
 };

apps/nextjs/src/components/board/sections/grid/grid-preview-layer.tsx

@@ -3,7 +3,7 @@
 import type { RefObject } from "react";
 import { useCallback, useLayoutEffect, useRef, useSyncExternalStore } from "react";
 
-import { getLayoutRowCount, getLogicalItemStyle, getLogicalTrackSize } from "~/components/board/layout";
+import { getLayoutRowCount, getLogicalItemStyle, getLogicalGridSize } from "~/components/board/layout";
 import type { TransactionalGridState } from "./dnd";
 import type { GridInteractionStore } from "./grid-interaction-store";
 import { clearGridPreviewGeometry, createGridPreviewDomState, syncGridPreviewGeometry } from "./grid-preview-geometry";
@@ -87,7 +87,7 @@ export const GridPreviewLayer = ({
     } else {
       delete grid.dataset.dndPreviewRevision;
     }
-    grid.style.height = `${getLogicalTrackSize(renderedRowCount)}px`;
+    grid.style.height = `${getLogicalGridSize(renderedRowCount)}px`;
 
     const viewport = grid.parentElement;
     if (viewport?.hasAttribute("data-section-id")) {
@@ -98,7 +98,7 @@ export const GridPreviewLayer = ({
       // stray value would silently blow the cap open for the rest of the session, well after any
       // drag ended, since nothing else would ever clear it back out.
       if (maxRowCount === null) {
-        viewport.style.setProperty("--board-grid-drag-height", `${getLogicalTrackSize(renderedRowCount)}px`);
+        viewport.style.setProperty("--board-grid-drag-height", `${getLogicalGridSize(renderedRowCount)}px`);
       } else {
         viewport.style.removeProperty("--board-grid-drag-height");
       }

apps/nextjs/src/components/board/sections/grid/grid-resize-outline.ts

@@ -1,4 +1,4 @@
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 import type { GridPlacement } from "~/components/board/layout";
 
 interface ResizeOutlinePreview {
@@ -31,8 +31,8 @@ export const createGridResizeOutlineController = (
     outline.style.position = "absolute";
     outline.style.left = `${(preview.placement.x - visualX) * LOGICAL_GRID_PITCH}px`;
     outline.style.top = `${(preview.placement.y - visualY) * LOGICAL_GRID_PITCH}px`;
-    outline.style.width = `${getLogicalTrackSize(preview.placement.w)}px`;
+    outline.style.width = `${getLogicalGridSize(preview.placement.w)}px`;
-    outline.style.height = `${getLogicalTrackSize(preview.placement.h)}px`;
+    outline.style.height = `${getLogicalGridSize(preview.placement.h)}px`;
     outline.dataset.gridResizeValid = String(preview.valid);
   };
 

apps/nextjs/src/components/board/sections/grid/section-grid.module.css

@@ -50,6 +50,10 @@
   overflow: visible;
 }
 
+.staticItem[data-type="item"] > .contentMount {
+  inset: calc(10px * var(--board-canvas-inverse-scale, 1));
+}
+
 .staticItem:has([data-board-container-label]) {
   z-index: 2;
 }

apps/nextjs/src/components/board/sections/grid/section-grid.tsx

@@ -14,7 +14,7 @@ import {
   getEditableCanvasAttributes,
   getGridRowCountForVisualHeight,
   getLayoutRowCount,
-  getLogicalTrackSize,
+  getLogicalGridSize,
   getReadonlyCanvasAttributes,
   normalizeGridPlacement,
 } from "~/components/board/layout";
@@ -138,9 +138,9 @@ export const SectionGrid = ({
   // of expanding to fit every widget, so its viewport height is capped independently of rowCount.
   const isScrollableContainer = section.kind === "container" && section.options.scrollable;
   const viewportRowCount = isScrollableContainer ? Math.max(requestedRowCount, 1) : rowCount;
-  const logicalWidth = getLogicalTrackSize(columnCount);
+  const logicalWidth = getLogicalGridSize(columnCount);
-  const logicalHeight = getLogicalTrackSize(rowCount);
+  const logicalHeight = getLogicalGridSize(rowCount);
-  const viewportHeight = getLogicalTrackSize(viewportRowCount);
+  const viewportHeight = getLogicalGridSize(viewportRowCount);
   // A collapsed container's compact coordinates are display-only. Its own
   // nested grid stays inactive until an explicit edit interaction expands it.
   const isInteractionDisabled = section.kind === "container" && collapsedSectionIds.has(section.id);

apps/nextjs/src/components/board/sections/grid/test/fixed-grid-item.spec.ts

@@ -4,7 +4,7 @@ import { createRoot } from "react-dom/client";
 import type { Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
-import { getCollapsedDisplayLayout, LOGICAL_GRID_CELL_SIZE } from "../../../layout";
+import { getCollapsedDisplayLayout, getLogicalGridSize } from "../../../layout";
 import { FixedGridItem } from "../fixed-grid-item";
 
 const mocks = vi.hoisted(() => ({
@@ -250,14 +250,14 @@ describe("fixed grid item behavior", () => {
     expect(container.querySelector('[data-testid="board-grid-drag-affordance"]')).toBeNull();
   });
 
-  test("renders a view-only 1x1 card at the fixed 200px logical size", () => {
+  test("renders a view-only 1x1 card at the complete grid footprint", () => {
     mocks.editMode = false;
     renderWeather(root);
 
     const item = container.querySelector<HTMLElement>('[data-grid-id="weather"]');
     expect(item).not.toBeNull();
-    expect(item?.style.width).toBe(`${LOGICAL_GRID_CELL_SIZE}px`);
+    expect(item?.style.width).toBe(`${getLogicalGridSize(1)}px`);
-    expect(item?.style.height).toBe(`${LOGICAL_GRID_CELL_SIZE}px`);
+    expect(item?.style.height).toBe(`${getLogicalGridSize(1)}px`);
     expect(item?.getAttribute("role")).toBeNull();
 
     act(() => item?.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true })));

apps/nextjs/src/components/board/sections/grid/test/grid-preview-geometry.spec.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, test } from "vitest";
 
-import { getLogicalTrackSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
+import { getLogicalGridSize, LOGICAL_GRID_PITCH } from "~/components/board/layout";
 
 import { createGridPreviewDomState, syncGridPreviewGeometry } from "../grid-preview-geometry";
 
@@ -65,8 +65,8 @@ describe("grid preview geometry", () => {
     expect(active?.getAttribute("data-grid-preview")).toBe("true");
     expect(active?.style.getPropertyValue("--board-grid-preview-x")).toBe(`${LOGICAL_GRID_PITCH}px`);
     expect(active?.style.getPropertyValue("--board-grid-preview-y")).toBe(`${LOGICAL_GRID_PITCH}px`);
-    expect(active?.style.getPropertyValue("--board-grid-preview-width")).toBe(`${getLogicalTrackSize(3)}px`);
+    expect(active?.style.getPropertyValue("--board-grid-preview-width")).toBe(`${getLogicalGridSize(3)}px`);
-    expect(active?.style.getPropertyValue("--board-grid-preview-height")).toBe(`${getLogicalTrackSize(4)}px`);
+    expect(active?.style.getPropertyValue("--board-grid-preview-height")).toBe(`${getLogicalGridSize(4)}px`);
     expect(active?.dataset.gridW).toBe("3");
     expect(active?.dataset.gridH).toBe("4");
   });

apps/nextjs/src/components/board/sections/grid/test/grid-resize-outline.spec.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, test, vi } from "vitest";
 
-import { getLogicalTrackSize } from "~/components/board/layout";
+import { getLogicalGridSize } from "~/components/board/layout";
 
 import { createGridResizeOutlineController } from "../grid-resize-outline";
 
@@ -30,8 +30,8 @@ describe("grid resize outline", () => {
     const outline = shell.querySelector<HTMLElement>("[data-grid-resize-outline]");
     expect(outline?.style.left).toBe("0px");
     expect(outline?.style.top).toBe("0px");
-    expect(outline?.style.width).toBe(`${getLogicalTrackSize(1)}px`);
+    expect(outline?.style.width).toBe(`${getLogicalGridSize(1)}px`);
-    expect(outline?.style.height).toBe(`${getLogicalTrackSize(2)}px`);
+    expect(outline?.style.height).toBe(`${getLogicalGridSize(2)}px`);
     expect(outline?.dataset.gridResizeValid).toBe("false");
 
     controller.schedule(null);

packages/api/src/router/board.ts

@@ -86,6 +86,7 @@ interface BoardItemPlacementRectangle {
 
 const boardItemPlacementTails = new Map<string, Promise<void>>();
 const maxManageOverviewPreviewRows = 12;
+const manageOverviewInputSchema = z.object({ fullPreview: z.boolean().default(false) }).optional();
 
 const serializeBoardItemPlacementAsync = async <T>(boardId: string, operation: () => Promise<T>) => {
   const previous = boardItemPlacementTails.get(boardId) ?? Promise.resolve();
@@ -225,7 +226,7 @@ export const boardRouter = createTRPCRouter({
         isMobileHome: currentUser?.mobileHomeBoardId === board.id,
       }));
     }),
-  getManageOverview: publicProcedure.query(async ({ ctx }) => {
+  getManageOverview: publicProcedure.input(manageOverviewInputSchema).query(async ({ ctx, input }) => {
     const userId = ctx.session?.user.id;
     const { boardIds, currentUser, groupMemberships } = await getBoardAccessContextAsync(ctx.db, userId);
     const groupPermissionWhere = getBoardGroupPermissionWhere(groupMemberships);
@@ -306,7 +307,7 @@ export const boardRouter = createTRPCRouter({
                 inArray(itemLayouts.sectionId, rootSectionIds),
                 gte(itemLayouts.xOffset, 0),
                 gte(itemLayouts.yOffset, 0),
-                lt(itemLayouts.yOffset, maxManageOverviewPreviewRows),
+                input?.fullPreview ? undefined : lt(itemLayouts.yOffset, maxManageOverviewPreviewRows),
                 gt(itemLayouts.width, 0),
                 gt(itemLayouts.height, 0),
               ),
@@ -331,7 +332,7 @@ export const boardRouter = createTRPCRouter({
                 inArray(sectionLayouts.parentSectionId, rootSectionIds),
                 gte(sectionLayouts.xOffset, 0),
                 gte(sectionLayouts.yOffset, 0),
-                lt(sectionLayouts.yOffset, maxManageOverviewPreviewRows),
+                input?.fullPreview ? undefined : lt(sectionLayouts.yOffset, maxManageOverviewPreviewRows),
                 gt(sectionLayouts.width, 0),
                 gt(sectionLayouts.height, 0),
               ),
@@ -366,7 +367,7 @@ export const boardRouter = createTRPCRouter({
               inArray(itemLayouts.sectionId, previewContainerSectionIds),
               gte(itemLayouts.xOffset, 0),
               gte(itemLayouts.yOffset, 0),
-              lt(itemLayouts.yOffset, maxManageOverviewPreviewRows),
+              input?.fullPreview ? undefined : lt(itemLayouts.yOffset, maxManageOverviewPreviewRows),
               gt(itemLayouts.width, 0),
               gt(itemLayouts.height, 0),
             ),

packages/api/src/router/test/board.spec.ts

@@ -337,7 +337,7 @@ describe("getManageOverview", () => {
     expect(overview.map((board) => board.id)).not.toContain(hiddenBoardId);
   });
 
-  test("returns one compact base-layout preview for each accessible board", async () => {
+  test("returns compact previews by default and full previews on request", async () => {
     const db = createDb();
     const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
     const boardId = createId();
@@ -487,6 +487,10 @@ describe("getManageOverview", () => {
     expect(result[0]?.preview?.layouts).toHaveLength(1);
     expect(result[0]?.preview?.items.map((item) => item.id)).toEqual([itemId, nestedItemId]);
     expect(result[0]?.preview?.sections).toHaveLength(2);
+
+    const fullResult = await caller.getManageOverview({ fullPreview: true });
+
+    expect(fullResult[0]?.preview?.items.map((item) => item.id)).toEqual([itemId, offscreenItemId, nestedItemId]);
   });
 
   test("includes app and widget icons in compact previews", async () => {

packages/boards/src/context.tsx

@@ -10,12 +10,16 @@ import { clientApi } from "@homarr/api/client";
 import { boardViewportWidthCookieName, getLayoutIdForViewportWidth } from "./layout-selection";
 import { updateBoardName } from "./updater";
 
-const BoardContext = createContext<{
+type Board = RouterOutputs["board"]["getBoardByName"];
-  board: RouterOutputs["board"]["getBoardByName"];
+
+interface BoardContextValue {
+  board: Board;
   layoutOverrideId: string | null;
   currentLayout: string;
   initialViewportWidth: number;
-} | null>(null);
+}
+
+const BoardContext = createContext<BoardContextValue | null>(null);
 
 const subscribeToViewport = (onStoreChange: () => void) => {
   if (typeof window === "undefined") return () => undefined;
@@ -37,6 +41,23 @@ const subscribeToViewport = (onStoreChange: () => void) => {
   };
 };
 
+export const BoardPreviewProvider = ({ children, board }: PropsWithChildren<{ board: Board }>) => {
+  const currentLayout = board.layouts[0]?.id ?? "";
+
+  return (
+    <BoardContext.Provider
+      value={{
+        board,
+        layoutOverrideId: null,
+        currentLayout,
+        initialViewportWidth: 0,
+      }}
+    >
+      {children}
+    </BoardContext.Provider>
+  );
+};
+
 export const BoardProvider = ({
   children,
   initialBoard,

packages/translation/src/lang/en.json

@@ -2083,10 +2083,12 @@
           "label": "Section or rail"
         },
         "width": {
-          "label": "Width"
+          "label": "Width",
+          "shortLabel": "W"
         },
         "height": {
-          "label": "Height"
+          "label": "Height",
+          "shortLabel": "H"
         },
         "xOffset": {
           "label": "X offset"
@@ -2115,6 +2117,13 @@
         "loading": "Loading integration",
         "loadError": "This integration could not be loaded. Try again before changing its connection settings."
       },
+      "preview": {
+        "integrationRequired": "Choose a connection to preview this widget.",
+        "size": "Size"
+      },
+      "settings": {
+        "label": "Widget settings"
+      },
       "advancedOptions": {
         "label": "Advanced options",
         "title": "Advanced item options"
@@ -2192,8 +2201,51 @@
         "layout": {
           "label": "Layout",
           "option": {
+            "adaptive": {
+              "label": "Adaptive"
+            },
             "gridHorizontal": {
-              "label": "Grid horizontal"
+              "label": "Compact grid"
+            },
+            "icons": {
+              "label": "Icons"
+            }
+          }
+        },
+        "variant": {
+          "label": "Appearance",
+          "option": {
+            "soft": {
+              "label": "Soft"
+            },
+            "filled": {
+              "label": "Filled"
+            },
+            "outline": {
+              "label": "Outline"
+            },
+            "plain": {
+              "label": "Plain"
+            }
+          }
+        },
+        "spacing": {
+          "label": "Card spacing",
+          "option": {
+            "xs": {
+              "label": "Extra small"
+            },
+            "sm": {
+              "label": "Small"
+            },
+            "md": {
+              "label": "Medium"
+            },
+            "lg": {
+              "label": "Large"
+            },
+            "xl": {
+              "label": "Extra large"
             }
           }
         },
@@ -2210,17 +2262,21 @@
           "label": "Show border"
         },
         "customUrls": {
-          "label": "Custom links",
+          "label": "Custom links"
-          "description": "Add URLs directly without creating an App first"
         },
         "items": {
           "label": "Bookmarks",
+          "remove": "Remove bookmark",
           "apps": {
-            "label": "Apps",
+            "label": "Add bookmarks",
-            "placeholder": "Select one or more apps"
+            "description": "Paste URLs or find existing Apps. Drag the bookmarks below to reorder them.",
+            "placeholder": "Paste URLs or search Apps",
+            "addUrl": "Add this URL",
+            "hint": "Press Enter to add a URL. Paste comma-separated or one-per-line URLs to add several."
           }
         }
-      }
+      },
+      "empty": "Add a URL or App in the widget settings"
     },
     "archiveTeamWarrior": {
       "name": "ArchiveTeam Warrior",

packages/ui/src/theme.ts

@@ -25,6 +25,7 @@ export const theme = createTheme({
   },
 
   fontSizes: {
+    xxs: rem(11),
     xs: rem(12),
     sm: rem(14),
     md: rem(16),

packages/widgets/package.json

@@ -30,7 +30,8 @@
     "./widget-integration-select": "./src/widget-integration-select.tsx",
     "./modals": "./src/modals/index.ts",
     "./prefetch": "./src/prefetch.ts",
-    "./refetch-intervals": "./src/refetch-intervals.ts"
+    "./refetch-intervals": "./src/refetch-intervals.ts",
+    "./widget-card-shell": "./src/widget-card-shell.tsx"
   },
   "scripts": {
     "clean": "rm -rf .turbo node_modules",

packages/widgets/src/_inputs/common.tsx

@@ -16,7 +16,7 @@ export interface CommonWidgetInputProps<TKey extends WidgetOptionType> {
   boardId?: string;
 }
 
-type UseWidgetInputTranslationReturnType = (key: "label" | "description" | "placeholder") => string;
+type UseWidgetInputTranslationReturnType = (key: "label" | "description" | "placeholder" | "remove") => string;
 
 /**
  * Short description why as and unknown convertions are used below:

packages/widgets/src/_inputs/widget-sortable-item-list-input.tsx

@@ -96,6 +96,28 @@ export const WidgetSortedItemListInput = <TItem, TOptionValue extends UniqueIden
     updateItems((currentValues) => [...currentValues, options.uniqueIdentifier(item) as TOptionValue]);
   };
 
+  const migrateItems = useCallback(
+    (items: TItem[], optionsPatch: Record<string, unknown>) => {
+      const migratedEntries = items.map((item) => [options.uniqueIdentifier(item) as TOptionValue, item] as const);
+      setTempMap((previous) => {
+        const next = new Map(previous);
+        for (const [value, item] of migratedEntries) next.set(value, item);
+        return next;
+      });
+      form.setFieldValue("options", (currentOptions) => {
+        const currentItems = Array.isArray(currentOptions[property])
+          ? (currentOptions[property] as TOptionValue[])
+          : options.defaultValue;
+        const nextItems = [...currentItems];
+        for (const [value] of migratedEntries) {
+          if (!nextItems.includes(value)) nextItems.push(value);
+        }
+        return { ...currentOptions, ...optionsPatch, [property]: nextItems };
+      });
+    },
+    [form, options, property],
+  );
+
   const removeItem = useCallback(
     (value: TOptionValue) => {
       updateItems((currentValues) => currentValues.filter((candidate) => candidate !== value));
@@ -112,7 +134,13 @@ export const WidgetSortedItemListInput = <TItem, TOptionValue extends UniqueIden
   return (
     <Fieldset legend={t("label")}>
       <Stack>
-        <options.addButton addItem={addItem} removeItem={removeItem} values={values} />
+        <options.addButton
+          addItem={addItem}
+          migrateItems={migrateItems}
+          removeItem={removeItem}
+          values={values}
+          initialOptions={initialOptions}
+        />
 
         <DndContext
           sensors={sensors}
@@ -153,6 +181,7 @@ export const WidgetSortedItemListInput = <TItem, TOptionValue extends UniqueIden
                       index={index}
                       item={item}
                       removeItem={() => removeItem(value)}
+                      removeLabel={t("remove")}
                       options={options}
                     />
                   );
@@ -177,6 +206,7 @@ interface ItemProps<TItem, TOptionValue extends UniqueIdentifier> {
   item: TItem;
   index: number;
   removeItem: () => void;
+  removeLabel: string;
   options: CommonWidgetInputProps<"sortableItemList">["options"];
 }
 
@@ -185,6 +215,7 @@ const Item = <TItem, TOptionValue extends UniqueIdentifier>({
   index,
   item,
   removeItem,
+  removeLabel,
   options,
 }: ItemProps<TItem, TOptionValue>) => {
   const { attributes, isDragging, listeners, setNodeRef, setActivatorNodeRef, transform, transition } = useSortable({
@@ -220,6 +251,7 @@ const Item = <TItem, TOptionValue extends UniqueIdentifier>({
         key={index}
         item={item}
         removeItem={removeItem}
+        removeLabel={removeLabel}
         rootAttributes={attributes}
         handle={
           <ActionIcon

packages/widgets/src/bookmarks/add-button.tsx

@@ -1,79 +1,198 @@
 "use client";
 
-import type { MultiSelectProps } from "@mantine/core";
+import { useEffect, useMemo, useRef, useState } from "react";
-import { Group, Loader, MultiSelect } from "@mantine/core";
+import {
-import { IconCheck } from "@tabler/icons-react";
+  Avatar,
+  Combobox,
+  Group,
+  Loader,
+  PillsInput,
+  ScrollArea,
+  Stack,
+  Text,
+  ThemeIcon,
+  useCombobox,
+} from "@mantine/core";
+import { IconCheck, IconLink, IconPlus } from "@tabler/icons-react";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { useI18n } from "@homarr/translation/client";
 
 import type { SortableItemListInput } from "../options";
+import { createDirectBookmark, getBookmarkFaviconUrl, splitBookmarkUrls } from "./bookmark-item";
+import type { BookmarkItem } from "./bookmark-item";
 
 type SelectableApp = RouterOutputs["app"]["selectable"][number];
+export type BookmarkSelectionItem = SelectableApp | BookmarkItem;
 
-export const BookmarkAddButton: SortableItemListInput<SelectableApp, string>["AddButton"] = ({
+const createOptionValue = "$create-url";
+
+export const BookmarkAddButton: SortableItemListInput<BookmarkSelectionItem, string>["AddButton"] = ({
   addItem,
-  removeItem,
+  migrateItems,
   values,
+  initialOptions,
 }) => {
   const t = useI18n("widget.bookmarks.option.items.apps");
   const tCommon = useI18n("common");
   const tSelect = useI18n("app.action.select");
   const { data: apps = [], isPending, error } = clientApi.app.selectable.useQuery();
-  const appsById = new Map(apps.map((app) => [app.id, app]));
+  const [search, setSearch] = useState("");
+  const combobox = useCombobox({
+    onDropdownClose: () => combobox.resetSelectedOption(),
+    onDropdownOpen: () => combobox.updateSelectedOptionIndex("active"),
+  });
+  const selectedValues = useMemo(() => new Set(values), [values]);
+  const migrationStartedRef = useRef(false);
+  const legacyUrls = useMemo(() => {
+    if (!Array.isArray(initialOptions.customUrls)) return [];
+    return initialOptions.customUrls.filter((value): value is string => typeof value === "string");
+  }, [initialOptions.customUrls]);
 
-  const handleChange = (nextValues: string[]) => {
+  useEffect(() => {
-    const nextIds = new Set(nextValues);
+    if (migrationStartedRef.current || legacyUrls.length === 0) return;
-    for (const value of values) {
-      if (!nextIds.has(value)) removeItem(value);
-    }
 
-    const currentIds = new Set(values);
+    migrationStartedRef.current = true;
-    for (const value of nextValues) {
+    const legacyItems = legacyUrls.flatMap((url) => createDirectBookmark(url) ?? []);
-      if (currentIds.has(value)) continue;
+    migrateItems(legacyItems, { customUrls: [] });
-      const app = appsById.get(value);
+  }, [legacyUrls, migrateItems]);
-      if (app) addItem(app);
+
+  const normalizedSearch = search.trim().toLowerCase();
+  const filteredApps = apps.filter((app) => {
+    if (selectedValues.has(app.id)) return false;
+    if (normalizedSearch.length === 0) return true;
+
+    return app.name.toLowerCase().includes(normalizedSearch) || app.href?.toLowerCase().includes(normalizedSearch);
+  });
+  const pendingUrl = createDirectBookmark(search);
+
+  const addUrls = (input: string) => {
+    const nextValues = new Set(values);
+    for (const value of splitBookmarkUrls(input)) {
+      const item = createDirectBookmark(value);
+      if (!item || nextValues.has(item.id)) continue;
+      addItem(item);
+      nextValues.add(item.id);
     }
+    setSearch("");
+    combobox.closeDropdown();
   };
 
+  const handleOptionSubmit = (value: string) => {
+    if (value === createOptionValue) {
+      addUrls(search);
+      return;
+    }
+
+    const app = apps.find((candidate) => candidate.id === value);
+    if (app) addItem(app);
+    setSearch("");
+  };
+
+  const options = filteredApps.map((app) => (
+    <Combobox.Option value={app.id} key={app.id}>
+      <Group gap="sm" wrap="nowrap">
+        <Avatar src={app.iconUrl} name={app.name} color="gray" size={28} radius="sm">
+          <IconLink size={16} />
+        </Avatar>
+        <Stack gap={0} miw={0} flex={1}>
+          <Text size="sm" fw={600} truncate>
+            {app.name}
+          </Text>
+          <Text size="xs" c="dimmed" truncate>
+            {app.href}
+          </Text>
+        </Stack>
+        <IconPlus size={16} aria-hidden />
+      </Group>
+    </Combobox.Option>
+  ));
+
   return (
-    <MultiSelect
+    <Combobox
-      label={t("label")}
+      store={combobox}
-      placeholder={t("placeholder")}
+      onOptionSubmit={handleOptionSubmit}
-      value={values}
+      position="bottom-start"
-      onChange={handleChange}
+      middlewares={{ flip: true, shift: true }}
-      searchable
+      styles={{
-      clearable
+        dropdown: { overflow: "hidden" },
-      clearSearchOnChange
+        option: { borderRadius: "var(--mantine-radius-sm)" },
-      hidePickedOptions
+      }}
-      disabled={isPending || Boolean(error)}
+    >
-      error={error ? tCommon("error") : undefined}
+      <Combobox.DropdownTarget>
-      rightSection={isPending ? <Loader size="xs" /> : undefined}
+        <PillsInput
-      nothingFoundMessage={tSelect("notFound")}
+          label={t("label")}
-      renderOption={renderAppOption}
+          description={t("description")}
-      data={apps.map((app) => ({
+          error={error ? tCommon("error") : undefined}
-        value: app.id,
+          onClick={() => combobox.openDropdown()}
-        label: app.name,
+          leftSection={
-        iconUrl: app.iconUrl,
+            <ThemeIcon variant="light" size="sm" radius="xl">
-      }))}
+              <IconLink size={14} />
-    />
+            </ThemeIcon>
+          }
+          rightSection={isPending ? <Loader size="xs" /> : undefined}
+          styles={{ input: { minHeight: 44 } }}
+        >
+          <Combobox.EventsTarget>
+            <PillsInput.Field
+              value={search}
+              placeholder={t("placeholder")}
+              onFocus={() => combobox.openDropdown()}
+              onBlur={() => combobox.closeDropdown()}
+              onChange={(event) => {
+                setSearch(event.currentTarget.value);
+                combobox.openDropdown();
+                combobox.updateSelectedOptionIndex();
+              }}
+              onPaste={(event) => {
+                const pastedValue = event.clipboardData.getData("text");
+                if (splitBookmarkUrls(pastedValue).length < 2) return;
+                event.preventDefault();
+                addUrls(pastedValue);
+              }}
+              onKeyDown={(event) => {
+                if (event.key !== "Enter") return;
+                if (!pendingUrl) return;
+                event.preventDefault();
+                addUrls(search);
+              }}
+            />
+          </Combobox.EventsTarget>
+        </PillsInput>
+      </Combobox.DropdownTarget>
+
+      <Combobox.Dropdown>
+        <ScrollArea.Autosize mah={280} type="auto">
+          <Combobox.Options>
+            {pendingUrl && !selectedValues.has(pendingUrl.id) ? (
+              <Combobox.Option value={createOptionValue}>
+                <Group gap="sm" wrap="nowrap">
+                  <Avatar src={getBookmarkFaviconUrl(pendingUrl.href)} size={28} radius="sm" color="gray">
+                    <IconLink size={16} />
+                  </Avatar>
+                  <Stack gap={0} miw={0} flex={1}>
+                    <Text size="sm" fw={600} truncate>
+                      {t("addUrl")}
+                    </Text>
+                    <Text size="xs" c="dimmed" truncate>
+                      {pendingUrl.href}
+                    </Text>
+                  </Stack>
+                  <IconCheck size={16} aria-hidden />
+                </Group>
+              </Combobox.Option>
+            ) : null}
+            {options}
+            {!pendingUrl && options.length === 0 ? <Combobox.Empty>{tSelect("notFound")}</Combobox.Empty> : null}
+          </Combobox.Options>
+        </ScrollArea.Autosize>
+        <Combobox.Footer>
+          <Text size="xs" c="dimmed">
+            {t("hint")}
+          </Text>
+        </Combobox.Footer>
+      </Combobox.Dropdown>
+    </Combobox>
   );
 };
-
-const iconProps = {
-  stroke: 1.5,
-  color: "currentColor",
-  opacity: 0.6,
-  size: 18,
-};
-
-const renderAppOption: MultiSelectProps["renderOption"] = ({ option, checked }) => (
-  <Group flex="1" gap="xs">
-    {"iconUrl" in option && typeof option.iconUrl === "string" ? (
-      <img width={20} height={20} src={option.iconUrl} alt="" />
-    ) : null}
-    {option.label}
-    {checked && <IconCheck style={{ marginInlineStart: "auto" }} {...iconProps} />}
-  </Group>
-);

packages/widgets/src/bookmarks/bookmark-item.ts

@@ -0,0 +1,66 @@
+import { getSafeApplicationUrl } from "../common/application-url";
+
+export const directBookmarkPrefix = "url:";
+
+export interface BookmarkItem {
+  id: string;
+  name: string;
+  description: string | null;
+  iconUrl?: string;
+  href: string | null;
+}
+
+export const normalizeBookmarkUrl = (value: string): string | undefined => {
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) return undefined;
+
+  const directUrl = getSafeApplicationUrl(trimmedValue);
+  if (directUrl) return directUrl;
+
+  if (/^(?:localhost(?::\d+)?|(?:[\w-]+\.)+[\w-]+(?::\d+)?)(?:[/?#].*)?$/i.test(trimmedValue)) {
+    return getSafeApplicationUrl(`https://${trimmedValue}`);
+  }
+
+  return undefined;
+};
+
+export const getDirectBookmarkValue = (url: string) => `${directBookmarkPrefix}${url}`;
+
+export const getDirectBookmarkUrl = (value: string): string | undefined => {
+  if (!value.startsWith(directBookmarkPrefix)) return undefined;
+  return normalizeBookmarkUrl(value.slice(directBookmarkPrefix.length));
+};
+
+export const getBookmarkFaviconUrl = (href: string | null): string | undefined => {
+  const safeUrl = getSafeApplicationUrl(href);
+  if (!safeUrl) return undefined;
+
+  const url = new URL(safeUrl);
+  return `${url.origin}/favicon.ico`;
+};
+
+export const createDirectBookmark = (url: string): BookmarkItem | undefined => {
+  const href = normalizeBookmarkUrl(url);
+  if (!href) return undefined;
+
+  const parsedUrl = new URL(href);
+  return {
+    id: getDirectBookmarkValue(href),
+    name: parsedUrl.hostname,
+    description: null,
+    href,
+  };
+};
+
+export const splitBookmarkUrls = (value: string) =>
+  value.split(/\r?\n+/).flatMap((line) => {
+    const trimmedLine = line.trim();
+    if (trimmedLine.length === 0) return [];
+
+    const commaSeparatedValues = trimmedLine.split(",").map((part) => part.trim());
+    if (commaSeparatedValues.length > 1 && commaSeparatedValues.every((part) => normalizeBookmarkUrl(part))) {
+      return commaSeparatedValues;
+    }
+
+    return [trimmedLine];
+  });

packages/widgets/src/bookmarks/bookmark.module.css

@@ -1,45 +0,0 @@
-.card {
-  background-color: transparent;
-  border-color: rgb(from var(--mantine-color-secondaryColor-filled) r g b / calc(var(--opacity, 1) * 0.38));
-  transition:
-    background-color 120ms ease,
-    border-color 120ms ease;
-}
-
-.card:hover,
-.card:focus-within {
-  background-color: transparent;
-  border-color: rgb(from var(--mantine-color-secondaryColor-filled) r g b / calc(var(--opacity, 1) * 0.62));
-}
-
-.bookmarkButton:focus-visible {
-  outline: 2px solid var(--mantine-primary-color-filled);
-  outline-offset: 2px;
-  border-radius: var(--mantine-radius-sm);
-}
-
-.card:hover > div > div.bookmarkIcon {
-  background-color: var(--mantine-color-iconColor-filled-hover);
-}
-
-.bookmarkButton:focus-visible .bookmarkIcon {
-  background-color: var(--mantine-color-iconColor-filled-hover);
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .card {
-    transition: none;
-  }
-}
-
-.compactScrollViewport > div {
-  display: flex !important;
-  width: 100%;
-  min-height: 100%;
-}
-
-.compactScrollContent {
-  flex: 1;
-  min-width: 100%;
-  min-height: 100%;
-}

packages/widgets/src/bookmarks/bookmarks-widget.tsx

@@ -0,0 +1,368 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import {
+  Avatar,
+  Box,
+  Card,
+  Center,
+  Group,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Text,
+  ThemeIcon,
+  Tooltip,
+} from "@mantine/core";
+import { useReducedMotion } from "@mantine/hooks";
+import { IconArrowUpRight, IconBookmark, IconLink } from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { useRequiredBoard } from "@homarr/boards/context";
+import { useRegisterSpotlightContextResults } from "@homarr/spotlight";
+import { useI18n } from "@homarr/translation/client";
+
+import { getSafeAppHref, SAFE_NEW_TAB_REL } from "../common/application-url";
+import { getUsableWidgetQueryData } from "../common/query-state";
+import type { WidgetComponentProps } from "../definition";
+import { createDirectBookmark, getBookmarkFaviconUrl, getDirectBookmarkUrl } from "./bookmark-item";
+import type { BookmarkItem } from "./bookmark-item";
+import { getBookmarkCardDisplay, getBookmarkDisplayPlan } from "./layout";
+import type { BookmarkOrientation } from "./layout";
+
+type BookmarkVariant = WidgetComponentProps<"bookmarks">["options"]["variant"];
+
+export default function BookmarksWidget({
+  options,
+  itemId,
+  width,
+  height,
+  displayMode,
+}: WidgetComponentProps<"bookmarks">) {
+  const t = useI18n("widget.bookmarks");
+  const board = useRequiredBoard();
+  const advanced = displayMode === "advanced";
+  const appIds = useMemo(() => options.items.filter((value) => !getDirectBookmarkUrl(value)), [options.items]);
+  const apps =
+    getUsableWidgetQueryData(
+      clientApi.app.byIds.useQuery(appIds, {
+        select(selectedApps) {
+          return selectedApps;
+        },
+      }),
+    ) ?? [];
+  const appsById = new Map(apps.map((app) => [app.id, app]));
+  const configuredItems = options.items.flatMap((value) => {
+    const directUrl = getDirectBookmarkUrl(value);
+    if (directUrl) return createDirectBookmark(directUrl) ?? [];
+    return appsById.get(value) ?? [];
+  });
+  const configuredHrefs = new Set(configuredItems.map((item) => item.href));
+  const legacyItems = options.customUrls.flatMap((url) => {
+    const item = createDirectBookmark(url);
+    if (!item || configuredHrefs.has(item.href)) return [];
+    return [item];
+  });
+  const data = [...configuredItems, ...legacyItems];
+
+  useRegisterSpotlightContextResults(
+    `bookmark-${itemId}`,
+    data.flatMap((bookmark) => {
+      const href = getSafeAppHref(bookmark.href);
+      if (!href) return [];
+
+      return [
+        {
+          id: bookmark.id,
+          name: bookmark.name,
+          icon: bookmark.iconUrl ?? IconLink,
+          interaction() {
+            return {
+              type: "link" as const,
+              href,
+              newTab: false,
+            };
+          },
+        },
+      ];
+    }),
+    [data],
+  );
+
+  const plan = useMemo(
+    () =>
+      getBookmarkDisplayPlan({
+        advanced,
+        height: options.title.length > 0 ? height - 36 : height,
+        itemCount: data.length,
+        layout: options.layout,
+        width,
+      }),
+    [advanced, data.length, height, options.layout, options.title.length, width],
+  );
+
+  const cardDisplay = getBookmarkCardDisplay({
+    advanced,
+    hideHostname: options.hideHostname,
+    hideIcon: options.hideIcon,
+    hideTitle: options.hideTitle,
+    plan,
+  });
+
+  const cards = data.map((bookmark) => (
+    <BookmarkCard
+      key={bookmark.id}
+      bookmark={bookmark}
+      advanced={advanced}
+      orientation={cardDisplay.orientation}
+      showHostname={cardDisplay.showHostname}
+      showIcon={cardDisplay.showIcon}
+      showTitle={cardDisplay.showTitle}
+      openNewTab={options.openNewTab}
+      variant={options.variant}
+      withBorder={options.withBorder}
+      radius={board.itemRadius}
+      height={plan.itemHeight}
+      width={plan.horizontalScroll ? plan.itemWidth : undefined}
+    />
+  ));
+
+  return (
+    <Stack h="100%" mih={0} gap={height < 120 ? 6 : "sm"} p={height < 120 ? 6 : "sm"}>
+      {options.title.length > 0 ? (
+        <Text fz={11} fw={600} px={2} lh={1.2} lineClamp={1}>
+          {options.title}
+        </Text>
+      ) : null}
+
+      {data.length === 0 ? (
+        <Center flex={1}>
+          <Stack align="center" gap={6}>
+            <ThemeIcon variant="light" size="lg" radius="xl">
+              <IconBookmark size={20} />
+            </ThemeIcon>
+            <Text size="sm" c="dimmed" ta="center">
+              {t("empty")}
+            </Text>
+          </Stack>
+        </Center>
+      ) : (
+        <ScrollArea
+          type="hover"
+          scrollbars={plan.horizontalScroll ? "x" : "y"}
+          scrollbarSize={2}
+          scrollHideDelay={500}
+          offsetScrollbars
+          style={{ flex: 1, minHeight: 0 }}
+        >
+          <Box miw="100%" mih="100%" pb={2}>
+            {plan.horizontalScroll ? (
+              <Group gap={options.spacing} wrap="nowrap" mih="100%" align="stretch">
+                {cards}
+              </Group>
+            ) : (
+              <SimpleGrid cols={plan.columns} spacing={options.spacing} verticalSpacing={options.spacing}>
+                {cards}
+              </SimpleGrid>
+            )}
+          </Box>
+        </ScrollArea>
+      )}
+    </Stack>
+  );
+}
+
+interface BookmarkCardProps {
+  advanced: boolean;
+  bookmark: BookmarkItem;
+  height: number;
+  openNewTab: boolean;
+  orientation: BookmarkOrientation;
+  radius: string;
+  showHostname: boolean;
+  showIcon: boolean;
+  showTitle: boolean;
+  variant: BookmarkVariant;
+  width?: number;
+  withBorder: boolean;
+}
+
+const BookmarkCard = ({
+  advanced,
+  bookmark,
+  height,
+  openNewTab,
+  orientation,
+  radius,
+  showHostname,
+  showIcon,
+  showTitle,
+  variant,
+  width,
+  withBorder,
+}: BookmarkCardProps) => {
+  const [active, setActive] = useState(false);
+  const reduceMotion = useReducedMotion();
+  const href = getSafeAppHref(bookmark.href);
+  const hostname = bookmark.href ? getBookmarkHostname(bookmark.href) : undefined;
+  const iconUrl = bookmark.iconUrl ?? getBookmarkFaviconUrl(bookmark.href);
+  const iconOnly = orientation === "icon" || (!showTitle && !showHostname);
+  const background = getBookmarkBackground(variant, active);
+
+  const content =
+    orientation === "vertical" && !advanced ? (
+      <Stack h="100%" align="center" justify="center" gap={6} flex={1}>
+        {showIcon ? <BookmarkAvatar bookmark={bookmark} iconUrl={iconUrl} size={iconOnly ? 34 : 38} /> : null}
+        {showTitle ? (
+          <Text size="xxs" fw={600} lh={1.2} ta="center" lineClamp={2}>
+            {bookmark.name}
+          </Text>
+        ) : null}
+        {showHostname ? (
+          <Text fz={9} c="dimmed" ta="center" truncate w="100%">
+            {hostname}
+          </Text>
+        ) : null}
+      </Stack>
+    ) : (
+      <Group
+        h="100%"
+        gap={advanced ? "sm" : "xs"}
+        wrap="nowrap"
+        justify={iconOnly ? "center" : "flex-start"}
+        align="center"
+        flex={1}
+      >
+        {showIcon ? (
+          <BookmarkAvatar bookmark={bookmark} iconUrl={iconUrl} size={advanced ? 42 : iconOnly ? 32 : 30} />
+        ) : null}
+        {!iconOnly ? (
+          <Stack gap={advanced ? 3 : 0} miw={0} flex={1}>
+            {showTitle ? (
+              <Text size={advanced ? "xs" : "xxs"} fw={600} lh={1.2} truncate>
+                {bookmark.name}
+              </Text>
+            ) : null}
+            {showHostname ? (
+              <Text fz={advanced ? 10 : 9} c="dimmed" truncate>
+                {hostname}
+              </Text>
+            ) : null}
+            {advanced && bookmark.description ? (
+              <Text fz={10} c="dimmed" lineClamp={2}>
+                {bookmark.description}
+              </Text>
+            ) : null}
+          </Stack>
+        ) : null}
+        {advanced ? (
+          <ThemeIcon
+            variant={active ? "light" : "transparent"}
+            color={active ? "primaryColor" : "gray"}
+            size="sm"
+            radius="xl"
+            style={{
+              opacity: active ? 1 : 0.45,
+              transform: active && !reduceMotion ? "translate(1px, -1px)" : undefined,
+              transition: reduceMotion ? undefined : "opacity 120ms ease, transform 120ms ease",
+            }}
+          >
+            <IconArrowUpRight size={14} />
+          </ThemeIcon>
+        ) : null}
+      </Group>
+    );
+
+  return (
+    <Tooltip
+      label={
+        <Stack gap={0}>
+          <Text size="xs" fw={600}>
+            {bookmark.name}
+          </Text>
+          {hostname ? (
+            <Text size="xs" opacity={0.8}>
+              {hostname}
+            </Text>
+          ) : null}
+        </Stack>
+      }
+      openDelay={450}
+      disabled={advanced}
+      withArrow
+    >
+      <Card
+        component={href ? "a" : "div"}
+        href={href}
+        target={href ? (openNewTab ? "_blank" : "_self") : undefined}
+        rel={href && openNewTab ? SAFE_NEW_TAB_REL : undefined}
+        aria-label={bookmark.name}
+        radius={radius}
+        withBorder={withBorder || variant === "outline"}
+        p={iconOnly ? 6 : advanced ? "md" : "xs"}
+        h={height}
+        w={width}
+        miw={width}
+        onMouseEnter={() => setActive(true)}
+        onMouseLeave={() => setActive(false)}
+        onFocus={() => setActive(true)}
+        onBlur={() => setActive(false)}
+        styles={{
+          root: {
+            background,
+            borderColor: active
+              ? "rgb(from var(--mantine-primary-color-filled) r g b / calc(var(--opacity, 1) * 0.62))"
+              : "rgb(from var(--mantine-color-secondaryColor-filled) r g b / calc(var(--opacity, 1) * 0.38))",
+            boxShadow: active ? "var(--mantine-shadow-sm)" : undefined,
+            color: "var(--mantine-color-text)",
+            cursor: href ? "pointer" : "default",
+            display: "flex",
+            outline: active ? "2px solid var(--mantine-primary-color-light)" : undefined,
+            outlineOffset: -2,
+            overflow: "hidden",
+            textDecoration: "none",
+            transform: active && !reduceMotion ? "translateY(-1px)" : undefined,
+            transition: reduceMotion
+              ? undefined
+              : "background-color 120ms ease, border-color 120ms ease, box-shadow 120ms ease, transform 120ms ease",
+          },
+        }}
+      >
+        {content}
+      </Card>
+    </Tooltip>
+  );
+};
+
+const BookmarkAvatar = ({ bookmark, iconUrl, size }: { bookmark: BookmarkItem; iconUrl?: string; size: number }) => (
+  <Avatar
+    src={iconUrl}
+    name={bookmark.name}
+    color="gray"
+    radius="sm"
+    size={size}
+    imageProps={{ referrerPolicy: "no-referrer" }}
+    styles={{ image: { objectFit: "contain" } }}
+  >
+    <IconLink size={Math.max(14, size / 2)} />
+  </Avatar>
+);
+
+const getBookmarkBackground = (variant: BookmarkVariant, active: boolean): string => {
+  if (variant === "plain" || variant === "outline") return "transparent";
+  if (variant === "filled") {
+    const opacity = active ? 0.64 : 0.48;
+    return `rgb(from var(--mantine-color-default-hover) r g b / calc(var(--opacity, 1) * ${opacity}))`;
+  }
+
+  const opacity = active ? 0.14 : 0.08;
+  return `rgb(from var(--mantine-primary-color-filled) r g b / calc(var(--opacity, 1) * ${opacity}))`;
+};
+
+const getBookmarkHostname = (href: string): string | undefined => {
+  try {
+    return new URL(href).hostname || undefined;
+  } catch {
+    return undefined;
+  }
+};

packages/widgets/src/bookmarks/component.tsx

@@ -1,532 +1,3 @@
 "use client";
 
-import type { CSSProperties } from "react";
+export { default } from "./bookmarks-widget";
-import { useMemo } from "react";
-import { Anchor, Card, Flex, Group, ScrollArea, SimpleGrid, Stack, Text, Title, UnstyledButton } from "@mantine/core";
-import { useElementSize } from "@mantine/hooks";
-import { IconLink } from "@tabler/icons-react";
-
-import { clientApi } from "@homarr/api/client";
-import { useRequiredBoard } from "@homarr/boards/context";
-import { useRegisterSpotlightContextResults } from "@homarr/spotlight";
-import { MaskedOrNormalImage } from "@homarr/ui";
-
-import type { WidgetComponentProps } from "../definition";
-import { getSafeApplicationUrl, getSafeAppHref, SAFE_NEW_TAB_REL } from "../common/application-url";
-import { getUsableWidgetQueryData } from "../common/query-state";
-import classes from "./bookmark.module.css";
-
-type BookmarkLayout = WidgetComponentProps<"bookmarks">["options"]["layout"];
-
-const COMPACT_GRID_GAP = 4;
-
-export interface BookmarkDisplayItem {
-  id: string;
-  name: string;
-  description: string | null;
-  iconUrl?: string;
-  href: string | null;
-}
-
-export interface CompactBookmarkLayout {
-  columns: number;
-  hideHostname: boolean;
-  hideTitle: boolean;
-  minimumItemSize: number;
-}
-
-export function getCompactBookmarkLayout(
-  width: number,
-  height: number,
-  itemCount: number,
-  layout: BookmarkLayout,
-): CompactBookmarkLayout {
-  const count = Math.max(1, itemCount);
-  const isGrid = layout === "grid" || layout === "gridHorizontal";
-  const targetWidth = layout === "gridHorizontal" ? 180 : 104;
-  let columns = 1;
-  if (isGrid) {
-    columns = Math.max(1, Math.min(count, Math.floor((width + COMPACT_GRID_GAP) / (targetWidth + COMPACT_GRID_GAP))));
-  } else if (layout === "row") {
-    columns = count;
-  }
-  const rows = Math.max(1, Math.ceil(count / columns));
-  const cellWidth = (width - (columns - 1) * COMPACT_GRID_GAP) / columns;
-  const cellHeight = height / rows;
-  const usesHorizontalItems = layout === "column" || layout === "gridHorizontal";
-
-  return {
-    columns,
-    hideHostname: cellWidth < 120 || cellHeight < (usesHorizontalItems ? 52 : 96),
-    hideTitle: cellWidth < 64 || cellHeight < 40,
-    minimumItemSize: usesHorizontalItems ? 48 : 96,
-  };
-}
-
-export default function BookmarksWidget({
-  options,
-  itemId,
-  width,
-  height,
-  displayMode,
-}: WidgetComponentProps<"bookmarks">) {
-  const board = useRequiredBoard();
-  const { ref: compactContentRef, width: compactContentWidth } = useElementSize<HTMLDivElement>();
-  const apps =
-    getUsableWidgetQueryData(
-      clientApi.app.byIds.useQuery(options.items, {
-        select(selectedApps) {
-          return selectedApps.toSorted((appA, appB) => options.items.indexOf(appA.id) - options.items.indexOf(appB.id));
-        },
-      }),
-    ) ?? [];
-  const customLinks = useMemo(
-    () => options.customUrls.flatMap((url) => createCustomBookmark(url) ?? []),
-    [options.customUrls],
-  );
-  const data: BookmarkDisplayItem[] = [...apps, ...customLinks];
-
-  useRegisterSpotlightContextResults(
-    `bookmark-${itemId}`,
-    data.flatMap((app) => {
-      const href = getSafeAppHref(app.href);
-      return href
-        ? [
-            {
-              id: app.id,
-              name: app.name,
-              icon: app.iconUrl ?? IconLink,
-              interaction() {
-                return {
-                  type: "link",
-                  href,
-                  newTab: false,
-                };
-              },
-            },
-          ]
-        : [];
-    }),
-    [data],
-  );
-
-  const compactLayout = useMemo(
-    () => getCompactBookmarkLayout(compactContentWidth || width, height, data.length, options.layout),
-    [compactContentWidth, data.length, height, options.layout, width],
-  );
-  const compactHideTitle = options.hideTitle || (compactLayout.hideTitle && !options.hideIcon);
-  const compactHideHostname =
-    options.hideHostname || (compactLayout.hideHostname && !(options.hideTitle && options.hideIcon));
-
-  return (
-    <Stack h="100%" mih={0} gap="sm" p={height < 120 ? "xs" : "sm"}>
-      {options.title.length > 0 && (
-        <Title order={4} px="0.25rem" lineClamp={displayMode === "advanced" ? undefined : 1}>
-          {options.title}
-        </Title>
-      )}
-      {displayMode === "advanced" && (
-        <AdvancedBookmarksLayout
-          data={data}
-          width={width}
-          openNewTab={options.openNewTab}
-          withBorder={options.withBorder}
-          hasIconColor={board.iconColor !== null}
-        />
-      )}
-      {displayMode !== "advanced" && (
-        <ScrollArea
-          classNames={{ viewport: classes.compactScrollViewport }}
-          type="auto"
-          scrollbarSize={6}
-          style={{ flex: 1, minHeight: 0 }}
-        >
-          <div ref={compactContentRef} className={classes.compactScrollContent}>
-            {options.layout === "grid" || options.layout === "gridHorizontal" ? (
-              <GridLayout
-                data={data}
-                columns={compactLayout.columns}
-                minimumItemHeight={compactLayout.minimumItemSize}
-                itemDirection={options.layout === "gridHorizontal" ? "horizontal" : "vertical"}
-                hideTitle={compactHideTitle}
-                hideIcon={options.hideIcon}
-                hideHostname={compactHideHostname}
-                openNewTab={options.openNewTab}
-                withBorder={options.withBorder}
-                hasIconColor={board.iconColor !== null}
-              />
-            ) : (
-              <FlexLayout
-                data={data}
-                direction={options.layout}
-                minimumItemSize={compactLayout.minimumItemSize}
-                hideTitle={compactHideTitle}
-                hideIcon={options.hideIcon}
-                hideHostname={compactHideHostname}
-                openNewTab={options.openNewTab}
-                withBorder={options.withBorder}
-                hasIconColor={board.iconColor !== null}
-              />
-            )}
-          </div>
-        </ScrollArea>
-      )}
-    </Stack>
-  );
-}
-
-interface FlexLayoutProps {
-  data: BookmarkDisplayItem[];
-  direction: "row" | "column";
-  hideTitle: boolean;
-  hideIcon: boolean;
-  hideHostname: boolean;
-  openNewTab: boolean;
-  withBorder: boolean;
-  hasIconColor: boolean;
-  minimumItemSize: number;
-}
-
-const FlexLayout = ({
-  data,
-  direction,
-  hideTitle,
-  hideIcon,
-  hideHostname,
-  openNewTab,
-  withBorder,
-  hasIconColor,
-  minimumItemSize,
-}: FlexLayoutProps) => {
-  const board = useRequiredBoard();
-  return (
-    <Flex direction={direction} gap={4} w="100%" mih="100%" wrap="nowrap">
-      {data.map((app) => {
-        const href = getSafeAppHref(app.href);
-        return (
-          <div key={app.id} style={{ display: "flex", flex: `1 0 ${minimumItemSize}px`, flexDirection: direction }}>
-            <UnstyledButton
-              className={classes.bookmarkButton}
-              component={href ? "a" : "div"}
-              href={href}
-              target={href ? (openNewTab ? "_blank" : "_self") : undefined}
-              rel={href && openNewTab ? SAFE_NEW_TAB_REL : undefined}
-              key={app.id}
-              w="100%"
-            >
-              <Card
-                radius={board.itemRadius}
-                className={classes.card}
-                bg="transparent"
-                w="100%"
-                display="flex"
-                p={4}
-                h="100%"
-                withBorder={withBorder}
-              >
-                {direction === "row" ? (
-                  <VerticalItem
-                    app={app}
-                    hideTitle={hideTitle}
-                    hideIcon={hideIcon}
-                    hideHostname={hideHostname}
-                    hasIconColor={hasIconColor}
-                  />
-                ) : (
-                  <HorizontalItem
-                    app={app}
-                    hideTitle={hideTitle}
-                    hideIcon={hideIcon}
-                    hideHostname={hideHostname}
-                    hasIconColor={hasIconColor}
-                  />
-                )}
-              </Card>
-            </UnstyledButton>
-          </div>
-        );
-      })}
-    </Flex>
-  );
-};
-
-interface AdvancedBookmarksLayoutProps {
-  data: BookmarkDisplayItem[];
-  width: number;
-  openNewTab: boolean;
-  withBorder: boolean;
-  hasIconColor: boolean;
-}
-
-export const getAdvancedBookmarkColumns = (width: number, itemCount: number): number =>
-  Math.max(1, Math.min(itemCount || 1, Math.floor(width / 280)));
-
-export const getBookmarkHostname = (href: string | null): string | undefined => {
-  const safeHref = getSafeApplicationUrl(href);
-  return safeHref ? new URL(safeHref).hostname : undefined;
-};
-
-export const createCustomBookmark = (url: string): BookmarkDisplayItem | null => {
-  const normalizedUrl = url.trim();
-  const href = getSafeAppHref(normalizedUrl);
-  if (!href) return null;
-
-  return {
-    id: `custom-link:${normalizedUrl}`,
-    name: getBookmarkHostname(href) ?? normalizedUrl,
-    description: null,
-    href,
-  };
-};
-
-const AdvancedBookmarksLayout = ({
-  data,
-  width,
-  openNewTab,
-  withBorder,
-  hasIconColor,
-}: AdvancedBookmarksLayoutProps) => {
-  const board = useRequiredBoard();
-
-  return (
-    <ScrollArea h="100%" style={{ flex: 1 }}>
-      <SimpleGrid cols={getAdvancedBookmarkColumns(width, data.length)} spacing="sm">
-        {data.map((app) => {
-          const href = getSafeAppHref(app.href);
-          return (
-            <UnstyledButton
-              key={app.id}
-              className={classes.bookmarkButton}
-              component={href ? "a" : "div"}
-              href={href}
-              target={href ? (openNewTab ? "_blank" : "_self") : undefined}
-              rel={href && openNewTab ? SAFE_NEW_TAB_REL : undefined}
-            >
-              <Card
-                radius={board.itemRadius}
-                className={classes.card}
-                bg="transparent"
-                withBorder={withBorder}
-                p="md"
-                h="100%"
-              >
-                <Group align="flex-start" wrap="nowrap">
-                  <BookmarkIcon
-                    app={app}
-                    hasColor={hasIconColor}
-                    className={classes.bookmarkIcon}
-                    style={{ width: 40, height: 40, flex: "0 0 auto" }}
-                  />
-                  <Stack gap={3} miw={0}>
-                    <Text fw={700} size="sm">
-                      {app.name}
-                    </Text>
-                    <Anchor component="span" size="xs" truncate="end">
-                      {getBookmarkHostname(app.href)}
-                    </Anchor>
-                    {app.description && (
-                      <Text size="xs" c="dimmed">
-                        {app.description}
-                      </Text>
-                    )}
-                  </Stack>
-                </Group>
-              </Card>
-            </UnstyledButton>
-          );
-        })}
-      </SimpleGrid>
-    </ScrollArea>
-  );
-};
-
-interface GridLayoutProps {
-  data: BookmarkDisplayItem[];
-  hideTitle: boolean;
-  hideIcon: boolean;
-  hideHostname: boolean;
-  openNewTab: boolean;
-  withBorder: boolean;
-  itemDirection: "horizontal" | "vertical";
-  hasIconColor: boolean;
-  columns: number;
-  minimumItemHeight: number;
-}
-
-const GridLayout = ({
-  data,
-  hideTitle,
-  hideIcon,
-  hideHostname,
-  openNewTab,
-  withBorder,
-  itemDirection,
-  hasIconColor,
-  columns,
-  minimumItemHeight,
-}: GridLayoutProps) => {
-  const board = useRequiredBoard();
-
-  return (
-    <Flex gap={COMPACT_GRID_GAP} wrap="wrap" miw="100%" mih="100%" style={{ alignContent: "stretch" }}>
-      {data.map((app) => {
-        const href = getSafeAppHref(app.href);
-        return (
-          <UnstyledButton
-            className={classes.bookmarkButton}
-            component={href ? "a" : "div"}
-            href={href}
-            target={href ? (openNewTab ? "_blank" : "_self") : undefined}
-            rel={href && openNewTab ? SAFE_NEW_TAB_REL : undefined}
-            key={app.id}
-            style={{
-              flex: `1 0 calc((100% - calc(${COMPACT_GRID_GAP * (columns - 1)}px * var(--mantine-scale, 1))) / ${columns})`,
-              minWidth: 0,
-              minHeight: `calc(${minimumItemHeight}px * var(--mantine-scale, 1))`,
-            }}
-          >
-            <Card
-              h="100%"
-              className={classes.card}
-              bg="transparent"
-              radius={board.itemRadius}
-              withBorder={withBorder}
-              p="xs"
-            >
-              {itemDirection === "horizontal" ? (
-                <HorizontalItem
-                  app={app}
-                  hideTitle={hideTitle}
-                  hideIcon={hideIcon}
-                  hideHostname={hideHostname}
-                  hasIconColor={hasIconColor}
-                />
-              ) : (
-                <VerticalItem
-                  app={app}
-                  hideTitle={hideTitle}
-                  hideIcon={hideIcon}
-                  hideHostname={hideHostname}
-                  hasIconColor={hasIconColor}
-                />
-              )}
-            </Card>
-          </UnstyledButton>
-        );
-      })}
-    </Flex>
-  );
-};
-
-const VerticalItem = ({
-  app,
-  hideTitle,
-  hideIcon,
-  hideHostname,
-  hasIconColor,
-}: {
-  app: BookmarkDisplayItem;
-  hideTitle: boolean;
-  hideIcon: boolean;
-  hideHostname: boolean;
-  hasIconColor: boolean;
-}) => {
-  return (
-    <Stack h="100%" miw={16} gap="sm" justify={"center"}>
-      {!hideTitle && (
-        <Text fw={700} ta="center" size="xs" lineClamp={2}>
-          {app.name}
-        </Text>
-      )}
-      {!hideIcon && (
-        <BookmarkIcon
-          app={app}
-          hasColor={hasIconColor}
-          className={classes.bookmarkIcon}
-          style={{
-            width: hideHostname && hideTitle ? "min(max(100%, 16px), 40px)" : 40,
-            height: hideHostname && hideTitle ? "min(max(100%, 16px), 40px)" : 40,
-            overflow: "auto",
-            flex: "unset",
-            marginLeft: "auto",
-            marginRight: "auto",
-          }}
-        />
-      )}
-      {!hideHostname && (
-        <Anchor ta="center" component="span" size="xs" truncate="end" w="100%">
-          {getBookmarkHostname(app.href)}
-        </Anchor>
-      )}
-    </Stack>
-  );
-};
-
-const HorizontalItem = ({
-  app,
-  hideTitle,
-  hideIcon,
-  hideHostname,
-  hasIconColor,
-}: {
-  app: BookmarkDisplayItem;
-  hideTitle: boolean;
-  hideIcon: boolean;
-  hideHostname: boolean;
-  hasIconColor: boolean;
-}) => {
-  return (
-    <Group wrap="nowrap" gap="xs" h="100%" justify="start">
-      {!hideIcon && (
-        <BookmarkIcon
-          app={app}
-          hasColor={hasIconColor}
-          className={classes.bookmarkIcon}
-          style={{
-            overflow: "auto",
-            width: hideHostname ? 16 : 24,
-            height: hideHostname ? 16 : 24,
-            flex: "unset",
-          }}
-        />
-      )}
-      {!(hideTitle && hideHostname) && (
-        <>
-          <Stack justify="space-between" gap={0} miw={0} style={{ flex: 1 }}>
-            {!hideTitle && (
-              <Text fw={700} size="xs" lineClamp={hideHostname ? 2 : 1}>
-                {app.name}
-              </Text>
-            )}
-
-            {!hideHostname && (
-              <Anchor component="span" size="xs" truncate="end">
-                {getBookmarkHostname(app.href)}
-              </Anchor>
-            )}
-          </Stack>
-        </>
-      )}
-    </Group>
-  );
-};
-
-interface BookmarkIconProps {
-  app: BookmarkDisplayItem;
-  hasColor: boolean;
-  className?: string;
-  style?: CSSProperties;
-}
-
-const BookmarkIcon = ({ app, hasColor, className, style }: BookmarkIconProps) =>
-  app.iconUrl ? (
-    <MaskedOrNormalImage
-      imageUrl={app.iconUrl}
-      hasColor={hasColor}
-      alt={app.name}
-      className={className}
-      style={style}
-    />
-  ) : (
-    <IconLink aria-label={app.name} className={className} style={style} />
-  );

packages/widgets/src/bookmarks/index.tsx

@@ -1,14 +1,13 @@
 import { ActionIcon, Avatar, Group, Stack, Text } from "@mantine/core";
-import { IconBookmark, IconX } from "@tabler/icons-react";
+import { IconBookmark, IconLink, IconX } from "@tabler/icons-react";
-import { z } from "zod/v4";
 
-import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 
-import { getSafeAppHref } from "../common/application-url";
 import { createWidgetDefinition } from "../definition";
 import { optionsBuilder } from "../options";
 import { BookmarkAddButton } from "./add-button";
+import type { BookmarkSelectionItem } from "./add-button";
+import { createDirectBookmark, getBookmarkFaviconUrl, getDirectBookmarkUrl } from "./bookmark-item";
 
 export const { definition, componentLoader } = createWidgetDefinition("bookmarks", {
   icon: IconBookmark,
@@ -18,42 +17,63 @@ export const { definition, componentLoader } = createWidgetDefinition("bookmarks
     return optionsBuilder.from((factory) => ({
       title: factory.text(),
       layout: factory.select({
-        options: (["grid", "gridHorizontal", "row", "column"] as const).map((value) => ({
+        options: (["adaptive", "column", "row", "grid", "gridHorizontal", "icons"] as const).map((value) => ({
           value,
           label: (t) => {
+            if (value === "adaptive") return t("widget.bookmarks.option.layout.option.adaptive.label");
             if (value === "grid") return t("widget.common.layout.option.grid");
             if (value === "row") return t("widget.common.layout.option.horizontal");
             if (value === "column") return t("widget.common.layout.option.vertical");
+            if (value === "icons") return t("widget.bookmarks.option.layout.option.icons.label");
             return t("widget.bookmarks.option.layout.option.gridHorizontal.label");
           },
         })),
-        defaultValue: "column",
+        defaultValue: "adaptive",
+      }),
+      variant: factory.select({
+        options: (["soft", "filled", "outline", "plain"] as const).map((value) => ({
+          value,
+          label: (t) => t(`widget.bookmarks.option.variant.option.${value}.label`),
+        })),
+        defaultValue: "soft",
+      }),
+      spacing: factory.select({
+        options: (["xs", "sm", "md", "lg", "xl"] as const).map((value) => ({
+          value,
+          label: (t) => t(`widget.bookmarks.option.spacing.option.${value}.label`),
+        })),
+        defaultValue: "xs",
       }),
       hideTitle: factory.switch({ defaultValue: false }),
       hideIcon: factory.switch({ defaultValue: false }),
       hideHostname: factory.switch({ defaultValue: false }),
       openNewTab: factory.switch({ defaultValue: true }),
       withBorder: factory.switch({ defaultValue: false }),
-      customUrls: factory.multiText({
+      customUrls: factory.internal({ defaultValue: [] as string[] }),
-        validate: z.string().refine((value) => getSafeAppHref(value) !== undefined),
+      items: factory.sortableItemList<BookmarkSelectionItem, string>({
-        withDescription: true,
+        ItemComponent: ({ item, handle, removeItem, removeLabel, rootAttributes }) => {
-      }),
+          const iconUrl = item.iconUrl ?? getBookmarkFaviconUrl(item.href);
-      items: factory.sortableItemList<RouterOutputs["app"]["selectable"][number], string>({
-        ItemComponent: ({ item, handle, removeItem, rootAttributes }) => {
           return (
             <Group {...rootAttributes} tabIndex={0} justify="space-between" wrap="nowrap">
-              <Group wrap="nowrap">
+              <Group wrap="nowrap" miw={0}>
                 {handle}
 
-                <Group>
+                <Group wrap="nowrap" miw={0}>
-                  <Avatar src={item.iconUrl} alt={item.name} />
+                  <Avatar src={iconUrl} name={item.name} color="gray" radius="sm">
-                  <Stack gap={0}>
+                    <IconLink size={20} />
-                    <Text>{item.name}</Text>
+                  </Avatar>
+                  <Stack gap={0} miw={0}>
+                    <Text fw={600} truncate>
+                      {item.name}
+                    </Text>
+                    <Text size="xs" c="dimmed" truncate>
+                      {item.href}
+                    </Text>
                   </Stack>
                 </Group>
               </Group>
 
-              <ActionIcon variant="transparent" color="red" onClick={removeItem}>
+              <ActionIcon variant="subtle" color="red" onClick={removeItem} aria-label={removeLabel}>
                 <IconX size="var(--mantine-font-size-xl)" />
               </ActionIcon>
             </Group>
@@ -62,7 +82,14 @@ export const { definition, componentLoader } = createWidgetDefinition("bookmarks
         AddButton: BookmarkAddButton,
         uniqueIdentifier: (item) => item.id,
         useData: (initialIds) => {
-          const { data, error, isLoading } = clientApi.app.byIds.useQuery(initialIds);
+          const appIds = initialIds.filter((value) => !getDirectBookmarkUrl(value));
+          const { data: apps, error, isLoading } = clientApi.app.byIds.useQuery(appIds);
+          const appsById = new Map(apps?.map((app) => [app.id, app]));
+          const data = initialIds.flatMap((value) => {
+            const directUrl = getDirectBookmarkUrl(value);
+            if (directUrl) return createDirectBookmark(directUrl) ?? [];
+            return appsById.get(value) ?? [];
+          });
 
           return {
             data,

packages/widgets/src/bookmarks/layout.spec.ts

@@ -1,54 +1,69 @@
 import { describe, expect, test } from "vitest";
 
-import {
+import { createDirectBookmark, normalizeBookmarkUrl, splitBookmarkUrls } from "./bookmark-item";
-  createCustomBookmark,
+import { getBookmarkCardDisplay, getBookmarkDisplayPlan } from "./layout";
-  getAdvancedBookmarkColumns,
-  getBookmarkHostname,
-  getCompactBookmarkLayout,
-} from "./component";
 
 describe("bookmark display helpers", () => {
-  test("uses bounded advanced columns", () => {
+  test("uses explicit width breakpoints for advanced columns", () => {
-    expect(getAdvancedBookmarkColumns(900, 8)).toBe(3);
+    expect(
-    expect(getAdvancedBookmarkColumns(120, 8)).toBe(1);
+      getBookmarkDisplayPlan({ advanced: true, width: 900, height: 500, itemCount: 8, layout: "adaptive" }),
-    expect(getAdvancedBookmarkColumns(900, 0)).toBe(1);
+    ).toMatchObject({
+      columns: 3,
+      orientation: "horizontal",
+    });
+    expect(
+      getBookmarkDisplayPlan({ advanced: true, width: 120, height: 500, itemCount: 8, layout: "adaptive" }),
+    ).toMatchObject({
+      columns: 1,
+      orientation: "horizontal",
+    });
   });
 
-  test("uses container geometry to keep compact cards legible", () => {
+  test("selects an adaptive plan from width and height breakpoints", () => {
-    expect(getCompactBookmarkLayout(420, 220, 4, "gridHorizontal")).toMatchObject({
+    expect(
+      getBookmarkDisplayPlan({ advanced: false, width: 560, height: 260, itemCount: 4, layout: "adaptive" }),
+    ).toMatchObject({
       columns: 2,
-      hideHostname: false,
+      itemHeight: 128,
-      hideTitle: false,
+      orientation: "horizontal",
-      minimumItemSize: 48,
+      showHostname: true,
+      showTitle: true,
     });
-
+    expect(
-    expect(getCompactBookmarkLayout(180, 80, 4, "row")).toMatchObject({
+      getBookmarkDisplayPlan({ advanced: false, width: 180, height: 80, itemCount: 4, layout: "adaptive" }),
-      columns: 4,
+    ).toMatchObject({
-      hideHostname: true,
+      columns: 1,
-      hideTitle: true,
+      orientation: "icon",
-      minimumItemSize: 96,
+      showHostname: false,
+      showTitle: false,
     });
   });
 
-  test("does not crash on malformed bookmark URLs", () => {
+  test("keeps compact cards visible when icons are hidden", () => {
-    expect(getBookmarkHostname("https://homarr.dev/docs")).toBe("homarr.dev");
+    const plan = getBookmarkDisplayPlan({ advanced: false, width: 180, height: 80, itemCount: 4, layout: "icons" });
-    expect(getBookmarkHostname("not a URL")).toBeUndefined();
+    expect(
-    expect(getBookmarkHostname(null)).toBeUndefined();
+      getBookmarkCardDisplay({ advanced: false, hideHostname: false, hideIcon: true, hideTitle: false, plan }),
+    ).toEqual({
+      orientation: "horizontal",
+      showHostname: false,
+      showIcon: false,
+      showTitle: true,
+    });
   });
 
   test("creates standalone bookmarks without app records", () => {
-    expect(createCustomBookmark("https://homarr.dev/docs")).toEqual({
+    expect(createDirectBookmark("https://homarr.dev/docs")).toEqual({
-      id: "custom-link:https://homarr.dev/docs",
+      id: "url:https://homarr.dev/docs",
       name: "homarr.dev",
       description: null,
       href: "https://homarr.dev/docs",
     });
-    expect(createCustomBookmark("  https://homarr.dev/docs  ")).toEqual({
+    expect(normalizeBookmarkUrl("homarr.dev/docs")).toBe("https://homarr.dev/docs");
-      id: "custom-link:https://homarr.dev/docs",
+    expect(normalizeBookmarkUrl("javascript:alert(1)")).toBeUndefined();
-      name: "homarr.dev",
+  });
-      description: null,
+
-      href: "https://homarr.dev/docs",
+  test("splits URL lists without corrupting commas inside a URL", () => {
-    });
+    expect(splitBookmarkUrls("https://one.example, two.example")).toEqual(["https://one.example", "two.example"]);
-    expect(createCustomBookmark("javascript:alert(1)")).toBeNull();
+    expect(splitBookmarkUrls("https://maps.example/@52.5,13.4,15z")).toEqual(["https://maps.example/@52.5,13.4,15z"]);
   });
 });

packages/widgets/src/bookmarks/layout.ts

@@ -0,0 +1,265 @@
+import type { WidgetComponentProps } from "../definition";
+
+export type BookmarkLayout = WidgetComponentProps<"bookmarks">["options"]["layout"];
+export type BookmarkOrientation = "horizontal" | "vertical" | "icon";
+
+export interface BookmarkDisplayPlan {
+  columns: number;
+  horizontalScroll: boolean;
+  itemHeight: number;
+  itemWidth: number;
+  orientation: BookmarkOrientation;
+  showHostname: boolean;
+  showTitle: boolean;
+}
+
+export interface BookmarkCardDisplay {
+  orientation: BookmarkOrientation;
+  showHostname: boolean;
+  showIcon: boolean;
+  showTitle: boolean;
+}
+
+export const getBookmarkCardDisplay = ({
+  advanced,
+  hideHostname,
+  hideIcon,
+  hideTitle,
+  plan,
+}: {
+  advanced: boolean;
+  hideHostname: boolean;
+  hideIcon: boolean;
+  hideTitle: boolean;
+  plan: BookmarkDisplayPlan;
+}): BookmarkCardDisplay => {
+  let orientation = plan.orientation;
+  let showTitle = advanced || (!hideTitle && plan.showTitle);
+  if (!advanced && hideIcon && !hideTitle && !showTitle) {
+    orientation = "horizontal";
+    showTitle = true;
+  }
+  const showHostname = advanced || (!hideHostname && plan.showHostname);
+  const showIcon = advanced || !hideIcon || (!showTitle && !showHostname);
+
+  return { orientation, showHostname, showIcon, showTitle };
+};
+
+interface BookmarkWidthBreakpoint {
+  adaptiveColumns: number;
+  adaptiveOrientation: BookmarkOrientation;
+  advancedColumns: number;
+  compactColumns: number;
+  gridColumns: number;
+  iconColumns: number;
+  minWidth: number;
+  rowItemWidth: number;
+  showHostname: boolean;
+  showTitle: boolean;
+}
+
+const widthBreakpoints = [
+  {
+    minWidth: 900,
+    adaptiveColumns: 4,
+    advancedColumns: 3,
+    compactColumns: 4,
+    gridColumns: 5,
+    iconColumns: 10,
+    rowItemWidth: 180,
+    adaptiveOrientation: "vertical",
+    showHostname: true,
+    showTitle: true,
+  },
+  {
+    minWidth: 720,
+    adaptiveColumns: 3,
+    advancedColumns: 2,
+    compactColumns: 3,
+    gridColumns: 4,
+    iconColumns: 8,
+    rowItemWidth: 172,
+    adaptiveOrientation: "horizontal",
+    showHostname: true,
+    showTitle: true,
+  },
+  {
+    minWidth: 480,
+    adaptiveColumns: 2,
+    advancedColumns: 2,
+    compactColumns: 2,
+    gridColumns: 3,
+    iconColumns: 6,
+    rowItemWidth: 160,
+    adaptiveOrientation: "horizontal",
+    showHostname: true,
+    showTitle: true,
+  },
+  {
+    minWidth: 300,
+    adaptiveColumns: 2,
+    advancedColumns: 1,
+    compactColumns: 1,
+    gridColumns: 2,
+    iconColumns: 4,
+    rowItemWidth: 144,
+    adaptiveOrientation: "horizontal",
+    showHostname: false,
+    showTitle: true,
+  },
+  {
+    minWidth: 0,
+    adaptiveColumns: 1,
+    advancedColumns: 1,
+    compactColumns: 1,
+    gridColumns: 1,
+    iconColumns: 2,
+    rowItemWidth: 112,
+    adaptiveOrientation: "icon",
+    showHostname: false,
+    showTitle: false,
+  },
+] as const satisfies readonly BookmarkWidthBreakpoint[];
+
+interface BookmarkHeightBreakpoint {
+  columnItemHeight: number;
+  itemHeight: number;
+  minHeight: number;
+  orientation: BookmarkOrientation;
+  rowItemHeight: number;
+  showHostname: boolean;
+  showTitle: boolean;
+}
+
+const heightBreakpoints = [
+  {
+    minHeight: 300,
+    columnItemHeight: 72,
+    itemHeight: 128,
+    rowItemHeight: 128,
+    orientation: "vertical",
+    showHostname: true,
+    showTitle: true,
+  },
+  {
+    minHeight: 180,
+    columnItemHeight: 64,
+    itemHeight: 128,
+    rowItemHeight: 112,
+    orientation: "horizontal",
+    showHostname: true,
+    showTitle: true,
+  },
+  {
+    minHeight: 110,
+    columnItemHeight: 56,
+    itemHeight: 80,
+    rowItemHeight: 80,
+    orientation: "horizontal",
+    showHostname: false,
+    showTitle: true,
+  },
+  {
+    minHeight: 0,
+    columnItemHeight: 48,
+    itemHeight: 56,
+    rowItemHeight: 56,
+    orientation: "icon",
+    showHostname: false,
+    showTitle: false,
+  },
+] as const satisfies readonly BookmarkHeightBreakpoint[];
+
+export const getBookmarkDisplayPlan = ({
+  advanced,
+  height,
+  itemCount,
+  layout,
+  width,
+}: {
+  advanced: boolean;
+  height: number;
+  itemCount: number;
+  layout: BookmarkLayout;
+  width: number;
+}): BookmarkDisplayPlan => {
+  const count = Math.max(1, itemCount);
+  const normalizedWidth = Math.max(0, width);
+  const normalizedHeight = Math.max(0, height);
+  const widthSettings = widthBreakpoints.find(({ minWidth }) => normalizedWidth >= minWidth);
+  const heightSettings = heightBreakpoints.find(({ minHeight }) => normalizedHeight >= minHeight);
+  if (!widthSettings || !heightSettings) throw new Error("Bookmark breakpoints must cover all widget sizes");
+
+  if (advanced) {
+    return {
+      columns: Math.min(count, widthSettings.advancedColumns),
+      horizontalScroll: false,
+      itemHeight: 104,
+      itemWidth: 260,
+      orientation: "horizontal",
+      showHostname: true,
+      showTitle: true,
+    };
+  }
+
+  if (layout === "row") {
+    let orientation: BookmarkOrientation = "vertical";
+    if (!heightSettings.showTitle) orientation = "icon";
+    return {
+      columns: count,
+      horizontalScroll: true,
+      itemHeight: heightSettings.rowItemHeight,
+      itemWidth: widthSettings.rowItemWidth,
+      orientation,
+      showHostname: widthSettings.showHostname && heightSettings.showHostname,
+      showTitle: widthSettings.showTitle && heightSettings.showTitle,
+    };
+  }
+
+  if (layout === "column") {
+    return {
+      columns: 1,
+      horizontalScroll: false,
+      itemHeight: heightSettings.columnItemHeight,
+      itemWidth: width,
+      orientation: "horizontal",
+      showHostname: widthSettings.showHostname && heightSettings.showHostname,
+      showTitle: widthSettings.showTitle && heightSettings.showTitle,
+    };
+  }
+
+  if (layout === "icons") {
+    return {
+      columns: Math.min(count, widthSettings.iconColumns),
+      horizontalScroll: false,
+      itemHeight: 56,
+      itemWidth: 56,
+      orientation: "icon",
+      showHostname: false,
+      showTitle: false,
+    };
+  }
+
+  let columns: number = widthSettings.compactColumns;
+  let orientation: BookmarkOrientation = "horizontal";
+  if (layout === "grid") {
+    columns = widthSettings.gridColumns;
+    orientation = "vertical";
+  }
+  if (layout === "adaptive") {
+    columns = widthSettings.adaptiveColumns;
+    orientation = widthSettings.adaptiveOrientation;
+    if (heightSettings.orientation === "icon") orientation = "icon";
+    if (heightSettings.orientation === "horizontal" && orientation === "vertical") orientation = "horizontal";
+  }
+
+  return {
+    columns: Math.min(count, columns),
+    horizontalScroll: false,
+    itemHeight: heightSettings.itemHeight,
+    itemWidth: widthSettings.rowItemWidth,
+    orientation,
+    showHostname: orientation !== "icon" && widthSettings.showHostname && heightSettings.showHostname,
+    showTitle: orientation !== "icon" && widthSettings.showTitle && heightSettings.showTitle,
+  };
+};

packages/widgets/src/bookmarks/prefetch.ts

@@ -4,11 +4,12 @@ import { apps } from "@homarr/db/schema";
 
 import type { Prefetch } from "../definition";
 import { createTrpcQueryKey } from "../trpc-query-key";
+import { getDirectBookmarkUrl } from "./bookmark-item";
 
 const logger = createLogger({ module: "bookmarksWidgetPrefetch" });
 
 const prefetchAllAsync: Prefetch<"bookmarks"> = async (queryClient, items) => {
-  const appIds = items.flatMap((item) => item.options.items);
+  const appIds = items.flatMap((item) => item.options.items.filter((value) => !getDirectBookmarkUrl(value)));
   const distinctAppIds = [...new Set(appIds)];
 
   const dbApps = await db.query.apps.findMany({
@@ -16,13 +17,14 @@ const prefetchAllAsync: Prefetch<"bookmarks"> = async (queryClient, items) => {
   });
 
   for (const item of items) {
-    if (item.options.items.length === 0) {
+    const itemAppIds = item.options.items.filter((value) => !getDirectBookmarkUrl(value));
+    if (itemAppIds.length === 0) {
       continue;
     }
 
     queryClient.setQueryData(
-      createTrpcQueryKey("app.byIds", item.options.items),
+      createTrpcQueryKey("app.byIds", itemAppIds),
-      dbApps.filter((app) => item.options.items.includes(app.id)),
+      dbApps.filter((app) => itemAppIds.includes(app.id)),
     );
   }
 

packages/widgets/src/modals/widget-edit-modal.module.css

@@ -0,0 +1,191 @@
+.workspace {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--mantine-spacing-lg);
+  align-items: start;
+}
+
+.workspace[data-with-preview][data-with-settings] {
+  grid-template-columns: minmax(0, 3fr) auto minmax(34rem, 2fr);
+}
+
+.previewPanel {
+  position: sticky;
+  top: 0;
+  width: 100%;
+  max-width: 52rem;
+  min-width: 0;
+  justify-self: center;
+}
+
+.previewDimensions {
+  position: absolute;
+  z-index: 2;
+  top: var(--mantine-spacing-xs);
+  right: var(--mantine-spacing-xs);
+  pointer-events: none;
+}
+
+.previewSizeControls {
+  position: absolute;
+  z-index: 3;
+  top: var(--mantine-spacing-xs);
+  left: var(--mantine-spacing-xs);
+  padding: 0.25rem 0.375rem;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-sm);
+  background: color-mix(in srgb, var(--mantine-color-body) 92%, transparent);
+  box-shadow: var(--mantine-shadow-xs);
+  backdrop-filter: blur(8px);
+}
+
+.previewSizeInput {
+  width: 5rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.previewCanvas {
+  position: relative;
+  width: 100%;
+  height: clamp(24rem, calc(100dvh - 17rem), 44rem);
+  padding: var(--mantine-spacing-lg);
+  overflow: hidden;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-md);
+  background-color: light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-8));
+  background-image:
+    linear-gradient(to right, color-mix(in srgb, var(--mantine-color-dimmed) 14%, transparent) 1px, transparent 1px),
+    linear-gradient(to bottom, color-mix(in srgb, var(--mantine-color-dimmed) 14%, transparent) 1px, transparent 1px);
+  background-size: 2rem 2rem;
+}
+
+.previewDivider {
+  height: auto;
+  align-self: stretch;
+}
+
+.previewViewport {
+  position: relative;
+  flex: 0 0 auto;
+  animation: dock-widget 260ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+.previewWidget {
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: top left;
+}
+
+.previewContent {
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  user-select: none;
+}
+
+.settingsPanel {
+  min-width: 0;
+  max-height: calc(100dvh - 13rem);
+  padding-right: 0.25rem;
+  overflow-y: auto;
+  scrollbar-gutter: stable;
+}
+
+.settingsForm {
+  min-width: 0;
+}
+
+.fullWidthField {
+  grid-column: 1 / -1;
+}
+
+.switchOption {
+  display: flex;
+  cursor: pointer;
+  height: 4.5rem;
+  align-items: center;
+  padding: 0.625rem 0.75rem;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-sm);
+  background: var(--mantine-color-body);
+}
+
+.switchOption > *,
+.switchOption :global(.mantine-Switch-root),
+.switchOption :global(.mantine-Switch-body) {
+  width: 100%;
+}
+
+.switchOption :global(.mantine-Switch-body) {
+  flex-direction: row-reverse;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-md);
+}
+
+.switchOption :global(.mantine-Switch-labelWrapper) {
+  min-width: 0;
+  flex: 1;
+}
+
+.switchOption :global(.mantine-Switch-description) {
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+.footer {
+  position: sticky;
+  z-index: 3;
+  bottom: calc(var(--mantine-spacing-md) * -1);
+  margin-inline: calc(var(--mantine-spacing-md) * -1);
+  margin-bottom: calc(var(--mantine-spacing-md) * -1);
+  padding: var(--mantine-spacing-sm) var(--mantine-spacing-md);
+  border-top: 1px solid var(--mantine-color-default-border);
+  background: color-mix(in srgb, var(--mantine-color-body) 94%, transparent);
+  backdrop-filter: blur(10px);
+}
+
+@keyframes dock-widget {
+  from {
+    opacity: 0;
+    transform: translate(-1.25rem, 1rem) scale(0.92);
+  }
+
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@media (max-width: 68em) {
+  .workspace[data-with-preview][data-with-settings] {
+    grid-template-columns: 1fr;
+  }
+
+  .previewPanel {
+    position: static;
+    max-width: 44rem;
+  }
+
+  .previewDivider {
+    display: none;
+  }
+
+  .previewCanvas {
+    height: 24rem;
+  }
+
+  .settingsPanel {
+    max-height: none;
+    overflow: visible;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .previewViewport {
+    animation: none;
+  }
+}

packages/widgets/src/modals/widget-edit-modal.tsx

@@ -1,18 +1,38 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+/* eslint-disable react/no-unstable-nested-components -- Widget modules and definition-bound fallbacks are loaded dynamically. */
-import type { ComponentType, FormEvent } from "react";
+
-import { Box, Button, Group, Stack, Tabs, Text } from "@mantine/core";
+import { useEffect, useId, useRef, useState } from "react";
+import type { ComponentType, FormEvent, PropsWithChildren } from "react";
+import {
+  Alert,
+  Badge,
+  Box,
+  Button,
+  Center,
+  Divider,
+  Group,
+  NumberInput,
+  SimpleGrid,
+  Stack,
+  Tabs,
+  Text,
+  Tooltip,
+} from "@mantine/core";
 import { schemaResolver } from "@mantine/form";
-import { IconArrowLeft, IconPencil } from "@tabler/icons-react";
+import { useElementSize } from "@mantine/hooks";
+import { IconArrowLeft, IconEye, IconPencil, IconSettings } from "@tabler/icons-react";
+import { QueryErrorResetBoundary } from "@tanstack/react-query";
+import { ErrorBoundary } from "react-error-boundary";
 import { z } from "zod/v4";
 
 import { objectEntries } from "@homarr/common";
-import { useSession } from "@homarr/auth/client";
+import { IntegrationProvider, useSession } from "@homarr/auth/client";
 import { useOptionalBoard } from "@homarr/boards/context";
 import type { WidgetKind } from "@homarr/definitions";
-import { createModal, ModalFormFooter, modalSizeForm, useModalAction } from "@homarr/modals";
+import { createModal, modalSizeForm, useModalAction } from "@homarr/modals";
 import type { SettingsContextProps } from "@homarr/settings/creator";
+import { SpotlightProvider } from "@homarr/spotlight";
 import { useI18n } from "@homarr/translation/client";
 import { IntegrationAvatar } from "@homarr/ui";
 import { zodErrorMap } from "@homarr/validation/form/i18n";
@@ -21,13 +41,16 @@ import { getInputForType } from "../_inputs";
 import { FormProvider, useForm } from "../_inputs/form";
 import type { BoardItemAdvancedOptions } from "../../../validation/src/shared";
 import type { OptionsBuilderResult } from "../options";
-import type { WidgetDefinition } from "../definition";
+import type { WidgetComponentProps, WidgetDefinition } from "../definition";
+import { WidgetError } from "../errors/component";
 import { OPTIONS_SUPER_REFINE } from "../options";
 import type { IntegrationSelectOption } from "../widget-integration-select";
 import { WidgetIntegrationSelect } from "../widget-integration-select";
+import { WidgetCardShell, WidgetTitleBadge } from "../widget-card-shell";
 import { WidgetAdvancedOptionsModal } from "./widget-advanced-options-modal";
 import type { EmbeddedAppEditFormHandle } from "./embedded-app-edit-form";
 import { EmbeddedAppEditForm } from "./embedded-app-edit-form";
+import classes from "./widget-edit-modal.module.css";
 
 export interface WidgetEditModalState {
   options: Record<string, unknown>;
@@ -35,6 +58,17 @@ export interface WidgetEditModalState {
   advancedOptions: BoardItemAdvancedOptions;
 }
 
+export interface WidgetEditModalSize {
+  width: number;
+  height: number;
+}
+
+interface WidgetEditPreviewResizeOptions {
+  initialSize: WidgetEditModalSize;
+  maximumSize: WidgetEditModalSize;
+  getDimensions?: (size: WidgetEditModalSize) => { width: number; height: number; scale?: number };
+}
+
 export interface EmbeddedIntegrationEditFormHandle {
   submitIfDirty: () => Promise<boolean>;
 }
@@ -49,7 +83,7 @@ export interface WidgetEditModalProps<TSort extends WidgetKind> {
   kind: TSort;
   definition: WidgetDefinition;
   value: WidgetEditModalState;
-  onSuccessfulEdit: (value: WidgetEditModalState) => void;
+  onSuccessfulEdit: (value: WidgetEditModalState, size?: WidgetEditModalSize) => void;
   integrationData: IntegrationSelectOption[];
   integrationSupport: boolean;
   settings: SettingsContextProps;
@@ -59,8 +93,215 @@ export interface WidgetEditModalProps<TSort extends WidgetKind> {
   integrationEditForm?: ComponentType<EmbeddedIntegrationEditFormProps>;
   onIntegrationSaved?: () => void;
   onOpenNewIntegration?: (onCreated?: (id: string) => void) => void;
+  previewComponent?: ComponentType<WidgetComponentProps<TSort>>;
+  previewDimensions?: { width: number; height: number; scale?: number };
+  previewResize?: WidgetEditPreviewResizeOptions;
+  previewWrapper?: ComponentType<PropsWithChildren>;
 }
 
+interface WidgetEditPreviewProps {
+  kind: WidgetKind;
+  Component: ComponentType<WidgetComponentProps<WidgetKind>>;
+  definition: WidgetDefinition;
+  state: WidgetEditModalState;
+  itemId?: string;
+  boardId?: string;
+  dimensions?: { width: number; height: number; scale?: number };
+  integrationData: IntegrationSelectOption[];
+  onChangeOptions: (newOptions: Record<string, unknown>) => void;
+  resize?: {
+    size: WidgetEditModalSize;
+    maximumSize: WidgetEditModalSize;
+    onChange: (size: WidgetEditModalSize) => void;
+  };
+  PreviewWrapper?: ComponentType<PropsWithChildren>;
+}
+
+const PreviewRuntimeBoundary = ({
+  Wrapper,
+  children,
+}: PropsWithChildren<{ Wrapper?: ComponentType<PropsWithChildren> }>) => {
+  if (!Wrapper) return children;
+  return <Wrapper>{children}</Wrapper>;
+};
+
+const normalizePreviewSize = (size: WidgetEditModalSize, maximumSize: WidgetEditModalSize): WidgetEditModalSize => ({
+  width: Math.max(1, Math.min(Math.round(size.width), maximumSize.width)),
+  height: Math.max(1, Math.min(Math.round(size.height), maximumSize.height)),
+});
+
+const WidgetEditPreview = ({
+  kind,
+  Component,
+  definition,
+  state,
+  itemId,
+  boardId,
+  dimensions = { width: 400, height: 240 },
+  integrationData,
+  onChangeOptions,
+  resize,
+  PreviewWrapper,
+}: WidgetEditPreviewProps) => {
+  const t = useI18n();
+  const tItem = useI18n("item.edit");
+  const board = useOptionalBoard();
+  const generatedPreviewId = useId().replaceAll(":", "");
+  const { ref, width: availableWidth, height: availableHeight } = useElementSize<HTMLDivElement>();
+  const sourceWidth = Math.max(dimensions.width, 1);
+  const sourceHeight = Math.max(dimensions.height, 1);
+  let maximumScale = dimensions.scale ?? 0.9;
+  if (!Number.isFinite(maximumScale) || maximumScale <= 0) maximumScale = 0.9;
+  maximumScale = Math.min(maximumScale, 0.9);
+  let previewScale = maximumScale;
+  if (availableWidth > 0 && availableHeight > 0) {
+    previewScale = Math.min(availableWidth / sourceWidth, availableHeight / sourceHeight, maximumScale);
+  }
+  const previewWidth = sourceWidth * previewScale;
+  const previewHeight = sourceHeight * previewScale;
+
+  const hasIntegrationSupport = "supportedIntegrations" in definition;
+  const integrationRequired = hasIntegrationSupport && definition.integrationsRequired !== false;
+  const isMissingIntegration = integrationRequired && state.integrationIds.length === 0;
+  const previewIntegrations = integrationData
+    .filter((integration) => state.integrationIds.includes(integration.id))
+    .map((integration) => ({
+      id: integration.id,
+      permissions: integration.permissions ?? {
+        hasFullAccess: false,
+        hasInteractAccess: false,
+        hasUseAccess: false,
+      },
+    }));
+  let componentItemId = itemId;
+  if (kind === "assistant") componentItemId = `widget-preview-${generatedPreviewId}`;
+  const isPendingCustomWidget = kind === "customApi" && !itemId;
+  const previewOpacity = (board?.opacity ?? 100) / 100;
+  const handleResizeValue = (dimension: keyof WidgetEditModalSize, value: string | number) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || !resize) return;
+    resize.onChange(
+      normalizePreviewSize(
+        {
+          ...resize.size,
+          [dimension]: value,
+        },
+        resize.maximumSize,
+      ),
+    );
+  };
+
+  return (
+    <Stack className={classes.previewPanel} gap={0}>
+      <Center ref={ref} className={classes.previewCanvas}>
+        {resize && (
+          <Group className={classes.previewSizeControls} gap={6} wrap="nowrap">
+            <Text size="xs" fw={600} c="dimmed">
+              {tItem("preview.size")}
+            </Text>
+            <Tooltip label={t("item.moveResize.field.width.label")}>
+              <NumberInput
+                className={classes.previewSizeInput}
+                aria-label={t("item.moveResize.field.width.label")}
+                value={resize.size.width}
+                onChange={(value) => handleResizeValue("width", value)}
+                min={1}
+                max={resize.maximumSize.width}
+                step={1}
+                allowDecimal={false}
+                allowNegative={false}
+                clampBehavior="strict"
+                size="xs"
+                leftSection={t("item.moveResize.field.width.shortLabel")}
+                leftSectionPointerEvents="none"
+              />
+            </Tooltip>
+            <Text size="xs" c="dimmed" aria-hidden>
+              ×
+            </Text>
+            <Tooltip label={t("item.moveResize.field.height.label")}>
+              <NumberInput
+                className={classes.previewSizeInput}
+                aria-label={t("item.moveResize.field.height.label")}
+                value={resize.size.height}
+                onChange={(value) => handleResizeValue("height", value)}
+                min={1}
+                max={resize.maximumSize.height}
+                step={1}
+                allowDecimal={false}
+                allowNegative={false}
+                clampBehavior="strict"
+                size="xs"
+                leftSection={t("item.moveResize.field.height.shortLabel")}
+                leftSectionPointerEvents="none"
+              />
+            </Tooltip>
+          </Group>
+        )}
+        <Badge className={classes.previewDimensions} size="xs" variant="light" color="gray">
+          {Math.round(sourceWidth)} × {Math.round(sourceHeight)}
+        </Badge>
+        {isMissingIntegration ? (
+          <Alert color="gray" variant="light" icon={<IconEye size={18} />} maw={320}>
+            {tItem("preview.integrationRequired")}
+          </Alert>
+        ) : (
+          <Box className={classes.previewViewport} w={previewWidth} h={previewHeight}>
+            <WidgetCardShell
+              className={classes.previewWidget}
+              kind={kind}
+              advancedOptions={state.advancedOptions}
+              opacity={previewOpacity}
+              radius={board?.itemRadius}
+              w={sourceWidth}
+              h={sourceHeight}
+              p={0}
+              data-grid-item-content
+              style={{ transform: `scale(${previewScale})` }}
+            >
+              <WidgetTitleBadge
+                advancedOptions={state.advancedOptions}
+                opacity={previewOpacity}
+                radius={board?.itemRadius}
+              />
+              <QueryErrorResetBoundary>
+                {({ reset }) => (
+                  <ErrorBoundary
+                    onReset={reset}
+                    resetKeys={[state.options, state.integrationIds]}
+                    fallbackRender={({ resetErrorBoundary, error }) => (
+                      <WidgetError definition={definition} error={error} resetErrorBoundary={resetErrorBoundary} />
+                    )}
+                  >
+                    <PreviewRuntimeBoundary Wrapper={PreviewWrapper}>
+                      <SpotlightProvider>
+                        <IntegrationProvider integrations={previewIntegrations}>
+                          <div className={classes.previewContent} inert>
+                            <Component
+                              options={state.options as never}
+                              integrationIds={state.integrationIds}
+                              width={sourceWidth}
+                              height={sourceHeight}
+                              isEditMode={isPendingCustomWidget}
+                              displayMode="compact"
+                              boardId={boardId}
+                              itemId={componentItemId}
+                              setOptions={({ newOptions }) => onChangeOptions(newOptions as Record<string, unknown>)}
+                            />
+                          </div>
+                        </IntegrationProvider>
+                      </SpotlightProvider>
+                    </PreviewRuntimeBoundary>
+                  </ErrorBoundary>
+                )}
+              </QueryErrorResetBoundary>
+            </WidgetCardShell>
+          </Box>
+        )}
+      </Center>
+    </Stack>
+  );
+};
+
 export const getSelectedWidgetIntegrations = (
   integrationData: readonly IntegrationSelectOption[],
   selectedIds: readonly string[],
@@ -81,6 +322,12 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
   const [mountedIntegrationIds, setMountedIntegrationIds] = useState<string[]>([]);
   const [activeIntegrationId, setActiveIntegrationId] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  const [previewSize, setPreviewSize] = useState<WidgetEditModalSize | null>(() => {
+    const resize = innerProps.previewResize;
+    if (!resize) return null;
+    return normalizePreviewSize(resize.initialSize, resize.maximumSize);
+  });
+  const widgetFormId = useId();
 
   z.config({
     customError: zodErrorMap(t),
@@ -206,10 +453,13 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
         }
       }
 
-      innerProps.onSuccessfulEdit({
+      innerProps.onSuccessfulEdit(
-        ...values,
+        {
-        advancedOptions,
+          ...values,
-      });
+          advancedOptions,
+        },
+        previewSize ?? undefined,
+      );
       actions.closeModal();
     } finally {
       setIsSubmitting(false);
@@ -231,47 +481,149 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
       }
     : undefined;
 
+  const handlePreviewOptionsChange = (newOptions: Record<string, unknown>) => {
+    form.setFieldValue("options", {
+      ...form.values.options,
+      ...newOptions,
+    });
+  };
+
+  const selectedIntegrationKinds = innerProps.integrationData
+    .filter(({ id }) => form.values.integrationIds.includes(id))
+    .map(({ kind }) => kind);
+  const visibleOptions = Object.entries(options).filter(([, value]) => {
+    const Input = getInputForType(value.type);
+    if (!Input) {
+      return false;
+    }
+
+    return !value.shouldHide?.(form.values.options as never, selectedIntegrationKinds);
+  });
+  const switchOptions = visibleOptions.filter(([, value]) => value.type === "switch");
+  const otherOptions = visibleOptions.filter(([, value]) => value.type !== "switch");
+  const hasWidgetSettings = canConfigureWidget && (innerProps.integrationSupport || visibleOptions.length > 0);
+  const previewResize = innerProps.previewResize;
+  let previewDimensions = innerProps.previewDimensions;
+  let resizeControls: WidgetEditPreviewProps["resize"];
+  if (previewSize && previewResize?.getDimensions) {
+    previewDimensions = previewResize.getDimensions(previewSize);
+    resizeControls = {
+      size: previewSize,
+      maximumSize: previewResize.maximumSize,
+      onChange: setPreviewSize,
+    };
+  }
+
   const widgetFormContent = (
-    <Stack>
+    <Box
-      {canConfigureWidget && innerProps.integrationSupport && (
+      className={classes.workspace}
-        <WidgetIntegrationSelect
+      data-with-preview={innerProps.previewComponent ? true : undefined}
-          label={tItem("field.integrations.label")}
+      data-with-settings={hasWidgetSettings ? true : undefined}
-          data={innerProps.integrationData}
+    >
-          canSelectMultiple={maxIntegrations > 1}
+      {innerProps.previewComponent && (
-          withAsterisk={integrationsRequired}
+        <WidgetEditPreview
-          onOpenNewIntegration={canCreateIntegration ? handleOpenNewIntegration : undefined}
+          kind={innerProps.kind}
-          {...form.getInputProps("integrationIds")}
+          Component={innerProps.previewComponent}
+          definition={definition}
+          state={{ ...form.values, advancedOptions }}
+          itemId={innerProps.itemId}
+          boardId={innerProps.boardId ?? board?.id}
+          dimensions={previewDimensions}
+          integrationData={innerProps.integrationData}
+          onChangeOptions={handlePreviewOptionsChange}
+          resize={resizeControls}
+          PreviewWrapper={innerProps.previewWrapper}
         />
       )}
-      {canConfigureWidget &&
+      {innerProps.previewComponent && hasWidgetSettings && (
-        Object.entries(options).map(([key, value]) => {
+        <Divider orientation="vertical" className={classes.previewDivider} />
-          const Input = getInputForType(value.type);
+      )}
+      <form id={widgetFormId} className={classes.settingsForm} onSubmit={onFormSubmit} hidden={!hasWidgetSettings}>
+        {hasWidgetSettings && (
+          <Stack className={classes.settingsPanel} gap="sm">
+            <Group gap="xs" wrap="nowrap">
+              <IconSettings size={16} />
+              <Text fw={600} size="sm">
+                {tItem("settings.label")}
+              </Text>
+            </Group>
+            {canConfigureWidget && innerProps.integrationSupport && (
+              <Box className={classes.fullWidthField}>
+                <WidgetIntegrationSelect
+                  label={tItem("field.integrations.label")}
+                  data={innerProps.integrationData}
+                  canSelectMultiple={maxIntegrations > 1}
+                  withAsterisk={integrationsRequired}
+                  onOpenNewIntegration={canCreateIntegration ? handleOpenNewIntegration : undefined}
+                  {...form.getInputProps("integrationIds")}
+                />
+              </Box>
+            )}
+            {canConfigureWidget && (
+              <Stack gap="sm">
+                {switchOptions.length > 0 && (
+                  <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="sm" verticalSpacing="sm">
+                    {switchOptions.map(([key, value]) => {
+                      const Input = getInputForType(value.type);
+                      if (!Input) {
+                        return null;
+                      }
 
-          if (
+                      return (
-            !Input ||
+                        <Box
-            value.shouldHide?.(
+                          key={key}
-              form.values.options as never,
+                          className={classes.switchOption}
-              innerProps.integrationData
+                          data-option-type={value.type}
-                .filter(({ id }) => form.values.integrationIds.includes(id))
+                          onClick={(event) => {
-                .map(({ kind }) => kind),
+                            const target = event.target;
-            )
+                            if (target instanceof Element && target.closest("label, input")) return;
-          ) {
+                            const input = event.currentTarget.querySelector<HTMLInputElement>("input[type=checkbox]");
-            return null;
+                            if (!input?.disabled) input?.click();
-          }
+                          }}
+                        >
+                          <Input
+                            kind={innerProps.kind}
+                            property={key}
+                            options={value as never}
+                            initialOptions={innerProps.value.options}
+                            itemId={innerProps.itemId}
+                            boardId={innerProps.boardId ?? board?.id}
+                          />
+                        </Box>
+                      );
+                    })}
+                  </SimpleGrid>
+                )}
+                {otherOptions.map(([key, value]) => {
+                  const Input = getInputForType(value.type);
+                  if (!Input) {
+                    return null;
+                  }
 
-          return (
+                  return (
-            <Input
+                    <Box key={key} data-option-type={value.type}>
-              key={key}
+                      <Input
-              kind={innerProps.kind}
+                        kind={innerProps.kind}
-              property={key}
+                        property={key}
-              options={value as never}
+                        options={value as never}
-              initialOptions={innerProps.value.options}
+                        initialOptions={innerProps.value.options}
-              itemId={innerProps.itemId}
+                        itemId={innerProps.itemId}
-              boardId={innerProps.boardId ?? board?.id}
+                        boardId={innerProps.boardId ?? board?.id}
-            />
+                      />
-          );
+                    </Box>
-        })}
+                  );
-      {showResourceTabs ? (
+                })}
+              </Stack>
+            )}
+          </Stack>
+        )}
+      </form>
+    </Box>
+  );
+
+  const footer = (
+    <Box className={classes.footer}>
+      <Group justify="space-between" wrap="nowrap">
         <Button
           variant="subtle"
           type="button"
@@ -284,143 +636,111 @@ export const WidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>(({
         >
           {tItem("advancedOptions.label")}
         </Button>
-      ) : (
+        <Group gap="xs" wrap="nowrap">
-        <ModalFormFooter
+          <Button onClick={actions.closeModal} variant="subtle" color="gray">
-          onCancel={actions.closeModal}
+            {tCommon("action.cancel")}
-          leftSection={
+          </Button>
-            <Button
+          <Button type="submit" form={widgetFormId} loading={isSubmitting}>
-              variant="subtle"
+            {tCommon("action.saveChanges")}
-              type="button"
+          </Button>
-              onClick={() =>
+        </Group>
-                openModal({
+      </Group>
-                  advancedOptions,
+    </Box>
-                  onSuccess: setAdvancedOptions,
-                })
-              }
-            >
-              {tItem("advancedOptions.label")}
-            </Button>
-          }
-        />
-      )}
-    </Stack>
   );
 
   return (
-    <form onSubmit={onFormSubmit}>
+    <FormProvider form={form}>
-      <FormProvider form={form}>
+      <Stack gap="sm">
         {showResourceTabs ? (
-          <Stack>
+          <Tabs value={activeTab} onChange={setActiveTab}>
-            <Tabs value={activeTab} onChange={setActiveTab}>
+            <Tabs.List grow>
-              <Tabs.List grow>
+              <Tabs.Tab value="widget">{tItem("tab.widget")}</Tabs.Tab>
-                <Tabs.Tab value="widget">{tItem("tab.widget")}</Tabs.Tab>
+              {showAppTab && <Tabs.Tab value="app">{tItem("tab.app")}</Tabs.Tab>}
-                {showAppTab && <Tabs.Tab value="app">{tItem("tab.app")}</Tabs.Tab>}
+              {showIntegrationTab && <Tabs.Tab value="integration">{tItem("tab.integration")}</Tabs.Tab>}
-                {showIntegrationTab && <Tabs.Tab value="integration">{tItem("tab.integration")}</Tabs.Tab>}
+            </Tabs.List>
-              </Tabs.List>
+            <Tabs.Panel value="widget" pt="sm">
-              <Tabs.Panel value="widget" pt="md">
+              {widgetFormContent}
-                {widgetFormContent}
+            </Tabs.Panel>
+            {showAppTab && (
+              <Tabs.Panel value="app" pt="sm">
+                {appId && <EmbeddedAppEditForm appId={appId} handleRef={appEditRef} />}
               </Tabs.Panel>
-              {showAppTab && (
+            )}
-                <Tabs.Panel value="app" pt="md">
+            {showIntegrationTab && (
-                  {appId && <EmbeddedAppEditForm appId={appId} handleRef={appEditRef} />}
+              <Tabs.Panel value="integration" pt="sm">
-                </Tabs.Panel>
+                <Stack>
-              )}
+                  {displayedIntegrationId === null && (
-              {showIntegrationTab && (
+                    <>
-                <Tabs.Panel value="integration" pt="md">
+                      <Text size="sm" c="dimmed">
-                  <Stack>
+                        {tItem("integration.description")}
-                    {displayedIntegrationId === null && (
+                      </Text>
-                      <>
+                      {selectedIntegrations.map((integration) => {
-                        <Text size="sm" c="dimmed">
+                        const canEdit = editableIntegrationIds.includes(integration.id);
-                          {tItem("integration.description")}
+                        return (
-                        </Text>
+                          <Group key={integration.id} justify="space-between" wrap="nowrap" gap="sm">
-                        {selectedIntegrations.map((integration) => {
+                            <Group gap="sm" wrap="nowrap" style={{ minWidth: 0 }}>
-                          const canEdit = editableIntegrationIds.includes(integration.id);
+                              <IntegrationAvatar kind={integration.kind} size="sm" />
-                          return (
+                              <Stack gap={0} style={{ minWidth: 0 }}>
-                            <Group key={integration.id} justify="space-between" wrap="nowrap" gap="sm">
+                                <Text fw={600} size="sm" truncate>
-                              <Group gap="sm" wrap="nowrap" style={{ minWidth: 0 }}>
+                                  {integration.name}
-                                <IntegrationAvatar kind={integration.kind} size="sm" />
-                                <Stack gap={0} style={{ minWidth: 0 }}>
-                                  <Text fw={600} size="sm" truncate>
-                                    {integration.name}
-                                  </Text>
-                                  <Text size="xs" c="dimmed" truncate>
-                                    {integration.url}
-                                  </Text>
-                                </Stack>
-                              </Group>
-                              {canEdit ? (
-                                <Button
-                                  type="button"
-                                  variant="light"
-                                  leftSection={<IconPencil size={16} />}
-                                  onClick={() => beginEditingIntegration(integration.id)}
-                                  aria-label={tItem("integration.editLabel", { name: integration.name })}
-                                >
-                                  {tItem("integration.action")}
-                                </Button>
-                              ) : (
-                                <Text size="xs" c="dimmed" ta="end">
-                                  {tItem("integration.fullAccessRequired")}
                                 </Text>
-                              )}
+                                <Text size="xs" c="dimmed" truncate>
+                                  {integration.url}
+                                </Text>
+                              </Stack>
                             </Group>
-                          );
+                            {canEdit ? (
-                        })}
+                              <Button
-                      </>
+                                type="button"
-                    )}
+                                variant="light"
-                    {displayedIntegrationId !== null && selectedIntegrations.length > 1 && (
+                                leftSection={<IconPencil size={16} />}
-                      <Button
+                                onClick={() => beginEditingIntegration(integration.id)}
-                        type="button"
+                                aria-label={tItem("integration.editLabel", { name: integration.name })}
-                        variant="subtle"
+                              >
-                        leftSection={<IconArrowLeft size={16} />}
+                                {tItem("integration.action")}
-                        onClick={() => setActiveIntegrationId(null)}
+                              </Button>
-                        style={{ alignSelf: "start" }}
+                            ) : (
-                      >
+                              <Text size="xs" c="dimmed" ta="end">
-                        {tCommon("action.previous")}
+                                {tItem("integration.fullAccessRequired")}
-                      </Button>
+                              </Text>
-                    )}
+                            )}
-                    {integrationIdsToRender.map((integrationId) => (
+                          </Group>
-                      <Box key={integrationId} hidden={displayedIntegrationId !== integrationId}>
+                        );
-                        {IntegrationEditForm && (
+                      })}
-                          <IntegrationEditForm
+                    </>
-                            integrationId={integrationId}
+                  )}
-                            handleRef={getIntegrationEditRef(integrationId)}
+                  {displayedIntegrationId !== null && selectedIntegrations.length > 1 && (
-                            onSuccess={innerProps.onIntegrationSaved}
+                    <Button
-                          />
+                      type="button"
-                        )}
+                      variant="subtle"
-                      </Box>
+                      leftSection={<IconArrowLeft size={16} />}
-                    ))}
+                      onClick={() => setActiveIntegrationId(null)}
-                  </Stack>
+                      style={{ alignSelf: "start" }}
-                </Tabs.Panel>
+                    >
-              )}
+                      {tCommon("action.previous")}
-            </Tabs>
+                    </Button>
-            <Box
+                  )}
-              pos="sticky"
+                  {integrationIdsToRender.map((integrationId) => (
-              bottom={0}
+                    <Box key={integrationId} hidden={displayedIntegrationId !== integrationId}>
-              style={{
+                      {IntegrationEditForm && (
-                marginInline: "calc(var(--mantine-spacing-md) * -1)",
+                        <IntegrationEditForm
-                marginBottom: "calc(var(--mantine-spacing-md) * -1)",
+                          integrationId={integrationId}
-                paddingInline: "var(--mantine-spacing-md)",
+                          handleRef={getIntegrationEditRef(integrationId)}
-                paddingBlock: "var(--mantine-spacing-sm)",
+                          onSuccess={innerProps.onIntegrationSaved}
-                background: "var(--mantine-color-body)",
+                        />
-                borderTop: "1px solid var(--mantine-color-default-border)",
+                      )}
-              }}
+                    </Box>
-            >
+                  ))}
-              <Group justify="end">
+                </Stack>
-                <Button onClick={actions.closeModal} variant="subtle" color="gray">
+              </Tabs.Panel>
-                  {tCommon("action.cancel")}
+            )}
-                </Button>
+          </Tabs>
-                <Button type="submit" loading={isSubmitting}>
-                  {tCommon("action.saveChanges")}
-                </Button>
-              </Group>
-            </Box>
-          </Stack>
         ) : (
           widgetFormContent
         )}
-      </FormProvider>
+        {footer}
-    </form>
+      </Stack>
+    </FormProvider>
   );
 }).withOptions({
   keepMounted: true,

packages/widgets/src/options.ts

@@ -34,12 +34,15 @@ export interface SortableItemListInput<TItem, TOptionValue extends UniqueIdentif
 > {
   AddButton: (props: {
     addItem: (item: TItem) => void;
+    migrateItems: (items: TItem[], optionsPatch: Record<string, unknown>) => void;
     removeItem: (value: TOptionValue) => void;
     values: TOptionValue[];
+    initialOptions: Record<string, unknown>;
   }) => React.ReactNode;
   ItemComponent: (props: {
     item: TItem;
     removeItem: () => void;
+    removeLabel: string;
     rootAttributes: DraggableAttributes;
     handle: React.ReactNode;
   }) => React.ReactNode;

packages/widgets/src/weather/index.ts

@@ -26,8 +26,8 @@ export const { definition, componentLoader } = createWidgetDefinition("weather",
         isFormatFahrenheit: factory.switch(),
         disableTemperatureDecimals: factory.switch(),
         animateIcons: factory.switch(),
-        showHumidity: factory.switch({ defaultValue: false, withDescription: true }),
+        showHumidity: factory.switch({ defaultValue: false }),
-        showCurrentWindSpeed: factory.switch({ withDescription: true }),
+        showCurrentWindSpeed: factory.switch(),
         useImperialSpeed: factory.switch(),
         location: factory.location({
           defaultValue: {

packages/widgets/src/widget-card-shell.module.css

@@ -0,0 +1,34 @@
+.card {
+  @mixin dark {
+    --background-color: rgb(from var(--mantine-color-dark-6) r g b / var(--opacity));
+    --default-border-color: rgb(from var(--mantine-color-dark-4) r g b / var(--opacity));
+  }
+
+  @mixin light {
+    --background-color: rgb(from var(--mantine-color-white) r g b / var(--opacity));
+    --default-border-color: rgb(from var(--mantine-color-gray-3) r g b / var(--opacity));
+  }
+
+  background-color: var(--background-color) !important;
+  border-color: var(--border-color, var(--default-border-color)) !important;
+}
+
+.card.iframe {
+  background-color: transparent !important;
+  border-color: transparent !important;
+}
+
+.title {
+  @mixin dark {
+    --background-color: rgb(from var(--mantine-color-dark-6) r g b / var(--opacity));
+    --default-border-color: rgb(from var(--mantine-color-dark-4) r g b / var(--opacity));
+  }
+
+  @mixin light {
+    --background-color: rgb(from var(--mantine-color-white) r g b / var(--opacity));
+    --default-border-color: rgb(from var(--mantine-color-gray-3) r g b / var(--opacity));
+  }
+
+  background-color: var(--background-color) !important;
+  border-color: var(--border-color, var(--default-border-color)) !important;
+}

packages/widgets/src/widget-card-shell.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import type { AriaRole, CSSProperties, PropsWithChildren, Ref } from "react";
+import type { CardProps } from "@mantine/core";
+import { Badge, Card } from "@mantine/core";
+import combineClasses from "clsx";
+
+import type { WidgetKind } from "@homarr/definitions";
+import type { BoardItemAdvancedOptions } from "@homarr/validation/shared";
+
+import classes from "./widget-card-shell.module.css";
+
+const getOverflow = (kind: WidgetKind, hasCustomCssClasses: boolean): CSSProperties => {
+  if (kind === "systemResources") return { overflowX: "visible", overflowY: "visible" };
+  if (kind === "iframe" || kind === "assistant") return { overflowX: "hidden", overflowY: "hidden" };
+  if (hasCustomCssClasses) return {};
+  return { overflowX: "hidden", overflowY: "auto" };
+};
+
+interface WidgetCardShellProps extends PropsWithChildren<Omit<CardProps, "className" | "styles">> {
+  kind: WidgetKind;
+  advancedOptions: BoardItemAdvancedOptions;
+  opacity: number;
+  className?: string;
+  innerRef?: Ref<HTMLDivElement>;
+  id?: string;
+  role?: AriaRole;
+  "aria-label"?: string;
+  "data-advanced-focus-surface"?: boolean;
+  "data-grid-item-content"?: boolean;
+}
+
+export const WidgetCardShell = ({
+  kind,
+  advancedOptions,
+  opacity,
+  className,
+  innerRef,
+  children,
+  ...cardProps
+}: WidgetCardShellProps) => (
+  <Card
+    {...cardProps}
+    ref={innerRef}
+    className={combineClasses(
+      classes.card,
+      kind === "iframe" && classes.iframe,
+      `${kind}-wrapper`,
+      "board-grid-item-content",
+      advancedOptions.customCssClasses.join(" "),
+      className,
+    )}
+    styles={{
+      root: {
+        "--opacity": opacity,
+        "--border-color": advancedOptions.borderColor || undefined,
+        containerType: "size",
+        ...getOverflow(kind, advancedOptions.customCssClasses.length > 0),
+      } as CSSProperties,
+    }}
+  >
+    {children}
+  </Card>
+);
+
+interface WidgetTitleBadgeProps {
+  advancedOptions: BoardItemAdvancedOptions;
+  opacity: number;
+  radius: CardProps["radius"];
+}
+
+export const WidgetTitleBadge = ({ advancedOptions, opacity, radius }: WidgetTitleBadgeProps) => {
+  if (!advancedOptions.title?.trim()) return null;
+
+  return (
+    <Badge
+      pos="absolute"
+      style={{ zIndex: "var(--mantine-z-index-app)" }}
+      top={2}
+      left={16}
+      size="xs"
+      radius={radius}
+      styles={{
+        root: {
+          "--border-color": advancedOptions.borderColor || undefined,
+          "--opacity": opacity,
+        } as CSSProperties,
+      }}
+      className={classes.title}
+      c="var(--mantine-color-text)"
+    >
+      {advancedOptions.title}
+    </Badge>
+  );
+};