feat(board): allow to set icon color of widgets (#2228)

Co-authored-by: Andre Silva <asilva01@acuitysso.com>

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

@@ -2,7 +2,7 @@
 
 import type { PropsWithChildren } from "react";
 import type { MantineColorsTuple } from "@mantine/core";
-import { createTheme, darken, lighten, MantineProvider } from "@mantine/core";
+import { colorsTuple, createTheme, darken, lighten, MantineProvider } from "@mantine/core";
 
 import { useRequiredBoard } from "@homarr/boards/context";
 import type { ColorScheme } from "@homarr/definitions";
@@ -20,6 +20,7 @@ export const BoardMantineProvider = ({
     colors: {
       primaryColor: generateColors(board.primaryColor),
       secondaryColor: generateColors(board.secondaryColor),
+      iconColor: board.iconColor ? generateColors(board.iconColor) : colorsTuple("#000000"),
     },
     primaryColor: "primaryColor",
     autoContrast: true,

apps/nextjs/src/app/[locale]/boards/[name]/settings/_appereance.tsx

@@ -40,6 +40,7 @@ export const ColorSettingsContent = ({ board }: Props) => {
       primaryColor: board.primaryColor,
       secondaryColor: board.secondaryColor,
       opacity: board.opacity,
+      iconColor: board.iconColor ?? "",
       itemRadius: board.itemRadius,
     },
   });
@@ -101,6 +102,12 @@ export const ColorSettingsContent = ({ board }: Props) => {
             </InputWrapper>
           </Grid.Col>
           <Grid.Col span={{ sm: 12, md: 6 }}>
+            <ColorInput
+              label={t("board.field.iconColor.label")}
+              format="hex"
+              swatches={Object.values(theme.colors).map((color) => color[6])}
+              {...form.getInputProps("iconColor")}
+            />
             <Select
               label={t("board.field.itemRadius.label")}
               description={t("board.field.itemRadius.description")}

packages/api/src/router/board.ts

@@ -511,6 +511,7 @@ export const boardRouter = createTRPCRouter({
           primaryColor: input.primaryColor,
           secondaryColor: input.secondaryColor,
           opacity: input.opacity,
+          iconColor: input.iconColor,
 
           // custom css
           customCss: input.customCss,

packages/db/migrations/mysql/0027_acoustic_karma.sql

@@ -0,0 +1 @@
+ALTER TABLE `board` ADD `icon_color` text;

packages/db/migrations/mysql/meta/_journal.json

@@ -190,6 +190,13 @@
       "when": 1739907771355,
       "tag": "0026_add-border-radius",
       "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "5",
+      "when": 1739915526818,
+      "tag": "0027_acoustic_karma",
+      "breakpoints": true
     }
   ]
 }

packages/db/migrations/sqlite/0027_wooden_blizzard.sql

@@ -0,0 +1 @@
+ALTER TABLE `board` ADD `icon_color` text;

packages/db/migrations/sqlite/meta/_journal.json

@@ -190,6 +190,13 @@
       "when": 1739907755789,
       "tag": "0026_add-border-radius",
       "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "6",
+      "when": 1739915486467,
+      "tag": "0027_wooden_blizzard",
+      "breakpoints": true
     }
   ]
 }

packages/db/schema/mysql.ts

@@ -281,6 +281,7 @@ export const boards = mysqlTable("board", {
   opacity: int().default(100).notNull(),
   customCss: text(),
   columnCount: int().default(10).notNull(),
+  iconColor: text(),
   itemRadius: text().$type<MantineSize>().default("lg").notNull(),
   disableStatus: boolean().default(false).notNull(),
 });

packages/db/schema/sqlite.ts

@@ -266,6 +266,7 @@ export const boards = sqliteTable("board", {
   opacity: int().default(100).notNull(),
   customCss: text(),
   columnCount: int().default(10).notNull(),
+  iconColor: text(),
   itemRadius: text().$type<MantineSize>().default("lg").notNull(),
   disableStatus: int({ mode: "boolean" }).default(false).notNull(),
 });

packages/translation/src/lang/en.json

@@ -2088,6 +2088,9 @@
       "opacity": {
         "label": "Opacity"
       },
+      "iconColor": {
+        "label": "Icon color"
+      },
       "customCss": {
         "label": "Custom css for this board",
         "description": "Further, customize your dashboard using CSS, only recommended for experienced users",

packages/ui/src/components/index.tsx

@@ -12,3 +12,5 @@ export { UserAvatarGroup } from "./user-avatar-group";
 export { CustomPasswordInput } from "./password-input/password-input";
 export { IntegrationAvatar } from "./integration-avatar";
 export { BetaBadge } from "./beta-badge";
+export { MaskedImage } from "./masked-image";
+export { MaskedOrNormalImage } from "./masked-or-normal-image";

packages/ui/src/components/masked-image.module.css

@@ -0,0 +1,3 @@
+.maskedImage {
+  background-color: var(--image-color);
+}

packages/ui/src/components/masked-image.tsx

@@ -0,0 +1,49 @@
+import React from "react";
+import { getThemeColor, useMantineTheme } from "@mantine/core";
+import type { MantineColor } from "@mantine/core";
+import combineClasses from "clsx";
+import type { Property } from "csstype";
+
+import classes from "./masked-image.module.css";
+
+interface MaskedImageProps {
+  imageUrl: string;
+  color: MantineColor;
+  alt?: string;
+  style?: React.CSSProperties;
+  className?: string;
+  maskSize?: Property.MaskSize;
+  maskRepeat?: Property.MaskRepeat;
+  maskPosition?: Property.MaskPosition;
+}
+
+export const MaskedImage = ({
+  imageUrl,
+  color,
+  alt,
+  style,
+  className,
+  maskSize = "contain",
+  maskRepeat = "no-repeat",
+  maskPosition = "center",
+}: MaskedImageProps) => {
+  const theme = useMantineTheme();
+
+  return (
+    <div
+      className={combineClasses(classes.maskedImage, className)}
+      role="img"
+      aria-label={alt}
+      style={
+        {
+          ...style,
+          "--image-color": getThemeColor(color, theme),
+          maskSize,
+          maskRepeat,
+          maskPosition,
+          maskImage: `url(${imageUrl})`,
+        } as React.CSSProperties
+      }
+    />
+  );
+};

packages/ui/src/components/masked-or-normal-image.tsx

@@ -0,0 +1,55 @@
+import { Image } from "@mantine/core";
+import type { MantineColor } from "@mantine/core";
+import combineClasses from "clsx";
+import type { Property } from "csstype";
+
+import { MaskedImage } from "./masked-image";
+
+interface MaskedOrNormalImageProps {
+  imageUrl: string;
+  hasColor?: boolean;
+  color?: MantineColor;
+  alt?: string;
+  style?: React.CSSProperties;
+  className?: string;
+  fit?: Property.ObjectFit;
+  maskSize?: Property.MaskSize;
+  maskRepeat?: Property.MaskRepeat;
+  maskPosition?: Property.MaskPosition;
+}
+
+export const MaskedOrNormalImage = ({
+  imageUrl,
+  hasColor = true,
+  color = "iconColor",
+  alt,
+  style,
+  className,
+  fit = "contain",
+  maskSize = "contain",
+  maskRepeat = "no-repeat",
+  maskPosition = "center",
+}: MaskedOrNormalImageProps) => {
+  return hasColor ? (
+    <MaskedImage
+      imageUrl={imageUrl}
+      color={color}
+      alt={alt}
+      className={combineClasses("masked-image", className)}
+      maskSize={maskSize}
+      maskRepeat={maskRepeat}
+      maskPosition={maskPosition}
+      style={{
+        ...style,
+      }}
+    />
+  ) : (
+    <Image
+      className={combineClasses("normal-image", className)}
+      src={imageUrl}
+      alt={alt}
+      fit={fit}
+      style={{ ...style }}
+    />
+  );
+};

packages/validation/src/board.ts

@@ -13,6 +13,11 @@ import { commonItemSchema, createSectionSchema } from "./shared";
 
 const hexColorSchema = z.string().regex(/^#[0-9A-Fa-f]{6}$/);
 
+const hexColorNullableSchema = hexColorSchema
+  .or(z.literal(""))
+  .nullable()
+  .transform((value) => (value?.trim().length === 0 ? null : value));
+
 const boardNameSchema = z
   .string()
   .min(1)
@@ -58,6 +63,7 @@ const savePartialSettingsSchema = z
     opacity: z.number().min(0).max(100),
     customCss: z.string().max(16384),
     columnCount: z.number().min(1).max(24),
+    iconColor: hexColorNullableSchema,
     itemRadius: z.union([z.literal("xs"), z.literal("sm"), z.literal("md"), z.literal("lg"), z.literal("xl")]),
     disableStatus: z.boolean(),
   })

packages/widgets/src/app/app.module.css

@@ -8,6 +8,10 @@
   transition: scale 0.2s ease-in-out;
 }
 
-.appIcon:hover {
+.appWithUrl:hover > .appIcon {
   scale: 0.9;
 }
+
+.appWithUrl:hover > div.appIcon {
+  background-color: var(--mantine-color-iconColor-filled-hover);
+}

packages/widgets/src/app/component.tsx

@@ -11,6 +11,7 @@ import { useRequiredBoard } from "@homarr/boards/context";
 import { useSettings } from "@homarr/settings";
 import { useRegisterSpotlightContextResults } from "@homarr/spotlight";
 import { useI18n } from "@homarr/translation/client";
+import { MaskedOrNormalImage } from "@homarr/ui";
 
 import type { WidgetComponentProps } from "../definition";
 import classes from "./app.module.css";
@@ -69,7 +70,7 @@ export default function AppWidget({ options, isEditMode }: WidgetComponentProps<
         styles={{ tooltip: { maxWidth: 300 } }}
       >
         <Flex
-          className={combineClasses("app-flex-wrapper", app.name, app.id)}
+          className={combineClasses("app-flex-wrapper", app.name, app.id, app.href && classes.appWithUrl)}
           h="100%"
           w="100%"
           direction="column"
@@ -82,7 +83,16 @@ export default function AppWidget({ options, isEditMode }: WidgetComponentProps<
               {app.name}
             </Text>
           )}
-          <img src={app.iconUrl} alt={app.name} className={combineClasses(classes.appIcon, "app-icon")} />
+          <MaskedOrNormalImage
+            imageUrl={app.iconUrl}
+            hasColor={board.iconColor !== null}
+            alt={app.name}
+            className={combineClasses(classes.appIcon, "app-icon")}
+            style={{
+              height: "100%",
+              width: "100%",
+            }}
+          />
         </Flex>
       </Tooltip.Floating>
       {options.pingEnabled && !settings.forceDisableStatus && !board.disableStatus && app.href ? (

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

@@ -1,3 +1,7 @@
 .card:hover {
   background-color: var(--mantine-color-primaryColor-light-hover);
 }
+
+.card:hover > div > div.bookmarkIcon {
+  background-color: var(--mantine-color-iconColor-filled-hover);
+}

packages/widgets/src/bookmarks/component.tsx

@@ -1,15 +1,18 @@
 "use client";
 
-import { Anchor, Box, Card, Divider, Flex, Group, Image, Stack, Text, Title, UnstyledButton } from "@mantine/core";
+import { Anchor, Box, Card, Divider, Flex, Group, Stack, Text, Title, UnstyledButton } from "@mantine/core";
 
 import type { RouterOutputs } from "@homarr/api";
 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 classes from "./bookmark.module.css";
 
 export default function BookmarksWidget({ options, width, height, itemId }: WidgetComponentProps<"bookmarks">) {
+  const board = useRequiredBoard();
   const [data] = clientApi.app.byIds.useSuspenseQuery(options.items, {
     select(data) {
       return data.sort((appA, appB) => options.items.indexOf(appA.id) - options.items.indexOf(appB.id));
@@ -50,6 +53,7 @@ export default function BookmarksWidget({ options, width, height, itemId }: Widg
           hideIcon={options.hideIcon}
           hideHostname={options.hideHostname}
           openNewTab={options.openNewTab}
+          hasIconColor={board.iconColor !== null}
         />
       )}
       {options.layout !== "grid" && (
@@ -59,6 +63,7 @@ export default function BookmarksWidget({ options, width, height, itemId }: Widg
           hideIcon={options.hideIcon}
           hideHostname={options.hideHostname}
           openNewTab={options.openNewTab}
+          hasIconColor={board.iconColor !== null}
         />
       )}
     </Stack>
@@ -71,9 +76,10 @@ interface FlexLayoutProps {
   hideIcon: boolean;
   hideHostname: boolean;
   openNewTab: boolean;
+  hasIconColor: boolean;
 }
 
-const FlexLayout = ({ data, direction, hideIcon, hideHostname, openNewTab }: FlexLayoutProps) => {
+const FlexLayout = ({ data, direction, hideIcon, hideHostname, openNewTab, hasIconColor }: FlexLayoutProps) => {
   return (
     <Flex direction={direction} gap="0" h="100%" w="100%">
       {data.map((app, index) => (
@@ -102,9 +108,9 @@ const FlexLayout = ({ data, direction, hideIcon, hideHostname, openNewTab }: Fle
               p={0}
             >
               {direction === "row" ? (
-                <VerticalItem app={app} hideIcon={hideIcon} hideHostname={hideHostname} />
+                <VerticalItem app={app} hideIcon={hideIcon} hideHostname={hideHostname} hasIconColor={hasIconColor} />
               ) : (
-                <HorizontalItem app={app} hideIcon={hideIcon} hideHostname={hideHostname} />
+                <HorizontalItem app={app} hideIcon={hideIcon} hideHostname={hideHostname} hasIconColor={hasIconColor} />
               )}
             </Card>
           </UnstyledButton>
@@ -121,9 +127,10 @@ interface GridLayoutProps {
   hideIcon: boolean;
   hideHostname: boolean;
   openNewTab: boolean;
+  hasIconColor: boolean;
 }
 
-const GridLayout = ({ data, width, height, hideIcon, hideHostname, openNewTab }: GridLayoutProps) => {
+const GridLayout = ({ data, width, height, hideIcon, hideHostname, openNewTab, hasIconColor }: GridLayoutProps) => {
   // Calculates the perfect number of columns for the grid layout based on the width and height in pixels and the number of items
   const columns = Math.ceil(Math.sqrt(data.length * (width / height)));
 
@@ -146,7 +153,7 @@ const GridLayout = ({ data, width, height, hideIcon, hideHostname, openNewTab }:
           h="100%"
         >
           <Card withBorder style={{ containerType: "size" }} h="100%" className={classes.card} p="5cqmin">
-            <VerticalItem app={app} hideIcon={hideIcon} hideHostname={hideHostname} />
+            <VerticalItem app={app} hideIcon={hideIcon} hideHostname={hideHostname} hasIconColor={hasIconColor} />
           </Card>
         </UnstyledButton>
       ))}
@@ -158,10 +165,12 @@ const VerticalItem = ({
   app,
   hideIcon,
   hideHostname,
+  hasIconColor,
 }: {
   app: RouterOutputs["app"]["byIds"][number];
   hideIcon: boolean;
   hideHostname: boolean;
+  hasIconColor: boolean;
 }) => {
   return (
     <Stack h="100%" gap="5cqmin">
@@ -169,17 +178,18 @@ const VerticalItem = ({
         {app.name}
       </Text>
       {!hideIcon && (
-        <Image
+        <MaskedOrNormalImage
+          imageUrl={app.iconUrl}
+          hasColor={hasIconColor}
+          alt={app.name}
+          className={classes.bookmarkIcon}
           style={{
             maxHeight: "100%",
             maxWidth: "100%",
             overflow: "auto",
             flex: 1,
-            objectFit: "contain",
             scale: 0.8,
           }}
-          src={app.iconUrl}
-          alt={app.name}
         />
       )}
       {!hideHostname && (
@@ -195,26 +205,29 @@ const HorizontalItem = ({
   app,
   hideIcon,
   hideHostname,
+  hasIconColor,
 }: {
   app: RouterOutputs["app"]["byIds"][number];
   hideIcon: boolean;
   hideHostname: boolean;
+  hasIconColor: boolean;
 }) => {
   return (
     <Group wrap="nowrap">
       {!hideIcon && (
-        <Image
+        <MaskedOrNormalImage
+          imageUrl={app.iconUrl}
+          hasColor={hasIconColor}
+          alt={app.name}
+          className={classes.bookmarkIcon}
           style={{
             overflow: "auto",
-            objectFit: "contain",
             scale: 0.8,
             minHeight: "100cqh",
             maxHeight: "100cqh",
             minWidth: "100cqh",
             maxWidth: "100cqh",
           }}
-          src={app.iconUrl}
-          alt={app.name}
         />
       )}
       <Stack justify="space-between" gap={0}>

packages/widgets/src/dns-hole/controls/component.tsx

@@ -3,29 +3,19 @@
 import "../../widgets-common.css";
 
 import { useState } from "react";
-import {
-  ActionIcon,
-  Badge,
-  Button,
-  Card,
-  Flex,
-  Image,
-  ScrollArea,
-  Stack,
-  Text,
-  Tooltip,
-  UnstyledButton,
-} from "@mantine/core";
+import { ActionIcon, Badge, Button, Card, Flex, ScrollArea, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
 import { useDisclosure } from "@mantine/hooks";
 import { IconCircleFilled, IconClockPause, IconPlayerPlay, IconPlayerStop } from "@tabler/icons-react";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { useIntegrationsWithInteractAccess } from "@homarr/auth/client";
+import { useRequiredBoard } from "@homarr/boards/context";
 import { useIntegrationConnected } from "@homarr/common";
 import { integrationDefs } from "@homarr/definitions";
 import type { TranslationFunction } from "@homarr/translation";
 import { useI18n } from "@homarr/translation/client";
+import { MaskedOrNormalImage } from "@homarr/ui";
 
 import type { widgetKind } from ".";
 import type { WidgetComponentProps } from "../../definition";
@@ -39,6 +29,7 @@ export default function DnsHoleControlsWidget({
   integrationIds,
   isEditMode,
 }: WidgetComponentProps<typeof widgetKind>) {
+  const board = useRequiredBoard();
   // DnsHole integrations with interaction permissions
   const integrationsWithInteractions = useIntegrationsWithInteractAccess()
     .map(({ id }) => id)
@@ -275,6 +266,7 @@ export default function DnsHoleControlsWidget({
               setSelectedIntegrationIds={setSelectedIntegrationIds}
               open={open}
               t={t}
+              hasIconColor={board.iconColor !== null}
             />
           ))}
         </Stack>
@@ -297,6 +289,7 @@ interface ControlsCardProps {
   setSelectedIntegrationIds: (integrationId: string[]) => void;
   open: () => void;
   t: TranslationFunction;
+  hasIconColor: boolean;
 }
 
 const ControlsCard: React.FC<ControlsCardProps> = ({
@@ -306,6 +299,7 @@ const ControlsCard: React.FC<ControlsCardProps> = ({
   setSelectedIntegrationIds,
   open,
   t,
+  hasIconColor,
 }) => {
   const isConnected = useIntegrationConnected(data.integration.updatedAt, { timeout: 30000 });
   const isEnabled = data.summary.status ? data.summary.status === "enabled" : undefined;
@@ -313,6 +307,8 @@ const ControlsCard: React.FC<ControlsCardProps> = ({
   // Use all factors to infer the state of the action buttons
   const controlEnabled = isInteractPermitted && isEnabled !== undefined && isConnected;
 
+  const iconUrl = integrationDefs[data.integration.kind].iconUrl;
+
   return (
     <Card
       className={`dns-hole-controls-integration-item-outer-shell dns-hole-controls-integration-item-${data.integration.id} dns-hole-controls-integration-item-${data.integration.name}`}
@@ -322,13 +318,16 @@ const ControlsCard: React.FC<ControlsCardProps> = ({
       radius="2.5cqmin"
     >
       <Flex className="dns-hole-controls-item-container" gap="4cqmin" align="center" direction="row">
-        <Image
+        <MaskedOrNormalImage
+          imageUrl={iconUrl}
+          hasColor={hasIconColor}
+          alt={data.integration.name}
           className="dns-hole-controls-item-icon"
-          src={integrationDefs[data.integration.kind].iconUrl}
-          w="20cqmin"
-          h="20cqmin"
-          fit="contain"
-          style={{ filter: !isConnected ? "grayscale(100%)" : undefined }}
+          style={{
+            height: "20cqmin",
+            width: "20cqmin",
+            filter: !isConnected ? "grayscale(100%)" : undefined,
+          }}
         />
         <Flex className="dns-hole-controls-item-data-stack" direction="column" gap="1.5cqmin">
           <Text className="dns-hole-controls-item-integration-name" fz="7cqmin">

pnpm-lock.yaml

@@ -18934,4 +18934,4 @@ snapshots:
     dependencies:
       zod: 3.24.2
 
-  zod@3.24.2: {}
+  zod@3.24.2: {}