Icon
+
+ setVertexStyle({ iconUrl, iconImageType })
+ }
+ />
{
diff --git a/packages/graph-explorer/src/utils/lucideIcons.test.ts b/packages/graph-explorer/src/utils/lucideIcons.test.ts
new file mode 100644
index 000000000..ac69511ee
--- /dev/null
+++ b/packages/graph-explorer/src/utils/lucideIcons.test.ts
@@ -0,0 +1,113 @@
+import type dynamicIconImports from "lucide-react/dynamicIconImports";
+
+import {
+ allIconNamesSorted,
+ getLucideName,
+ getLucideSvgString,
+ isLucideIconRef,
+ isValidLucideIconName,
+ LUCIDE_PREFIX,
+ toLucideIconRef,
+} from "./lucideIcons";
+
+vi.mock("lucide-react/dynamicIconImports", async () => {
+ const actual = await vi.importActual("lucide-react/dynamicIconImports");
+ return {
+ ...actual,
+ default: {
+ ...(actual as { default: typeof dynamicIconImports }).default,
+ "throwing-icon": () => Promise.reject(new Error("import failed")),
+ },
+ };
+});
+
+describe("LUCIDE_PREFIX", () => {
+ it("is 'lucide:'", () => {
+ expect(LUCIDE_PREFIX).toBe("lucide:");
+ });
+});
+
+describe("isLucideIconRef", () => {
+ it("recognizes lucide refs", () => {
+ expect(isLucideIconRef("lucide:plane")).toBe(true);
+ expect(isLucideIconRef("lucide:log-in")).toBe(true);
+ });
+
+ it("rejects other values", () => {
+ expect(isLucideIconRef(undefined)).toBe(false);
+ expect(isLucideIconRef("")).toBe(false);
+ expect(isLucideIconRef("data:image/svg+xml;base64,XXX")).toBe(false);
+ expect(isLucideIconRef("https://example.com/icon.svg")).toBe(false);
+ });
+
+ it("narrows the type to a template literal", () => {
+ const url: string | undefined = "lucide:plane";
+ expect(isLucideIconRef(url)).toBe(true);
+ });
+});
+
+describe("isValidLucideIconName", () => {
+ it("accepts known icons", () => {
+ expect(isValidLucideIconName("user")).toBe(true);
+ expect(isValidLucideIconName("log-in")).toBe(true);
+ });
+
+ it("rejects unknown names", () => {
+ expect(isValidLucideIconName("not-a-real-icon")).toBe(false);
+ expect(isValidLucideIconName("")).toBe(false);
+ });
+});
+
+describe("getLucideName", () => {
+ it("extracts the name from a lucide ref", () => {
+ expect(getLucideName("lucide:plane")).toBe("plane");
+ expect(getLucideName("lucide:log-in")).toBe("log-in");
+ });
+
+ it("returns null for non-lucide values", () => {
+ expect(getLucideName(undefined)).toBeNull();
+ expect(getLucideName("")).toBeNull();
+ expect(getLucideName("data:image/svg+xml;base64,XXX")).toBeNull();
+ expect(getLucideName("https://example.com/icon.svg")).toBeNull();
+ });
+});
+
+describe("toLucideIconRef", () => {
+ it("builds a lucide ref", () => {
+ expect(toLucideIconRef("plane")).toBe("lucide:plane");
+ expect(toLucideIconRef("log-in")).toBe("lucide:log-in");
+ });
+});
+
+describe("allIconNamesSorted", () => {
+ it("is sorted alphabetically", () => {
+ const copy = [...allIconNamesSorted];
+ copy.sort();
+ expect(allIconNamesSorted).toEqual(copy);
+ });
+
+ it("contains known icons", () => {
+ expect(allIconNamesSorted).toContain("user");
+ expect(allIconNamesSorted).toContain("mail");
+ });
+});
+
+describe("getLucideSvgString", () => {
+ it("returns raw SVG markup for a valid icon", async () => {
+ const svg = await getLucideSvgString("user");
+ expect(svg).not.toBeNull();
+ expect(svg).toContain("");
+ expect(svg).toContain("currentColor");
+ });
+
+ it("returns null for an unknown icon", async () => {
+ const svg = await getLucideSvgString("not-a-real-icon-name");
+ expect(svg).toBeNull();
+ });
+
+ it("returns null when dynamic import throws", async () => {
+ const svg = await getLucideSvgString("throwing-icon");
+ expect(svg).toBeNull();
+ });
+});
diff --git a/packages/graph-explorer/src/utils/lucideIcons.ts b/packages/graph-explorer/src/utils/lucideIcons.ts
new file mode 100644
index 000000000..8a6405155
--- /dev/null
+++ b/packages/graph-explorer/src/utils/lucideIcons.ts
@@ -0,0 +1,63 @@
+import dynamicIconImports from "lucide-react/dynamicIconImports";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+/** A valid Lucide icon name (kebab-case, e.g. "user", "log-in"). */
+export type IconName = keyof typeof dynamicIconImports;
+
+/** All available Lucide icon names, sorted alphabetically. */
+export const allIconNamesSorted = (
+ Object.keys(dynamicIconImports) as IconName[]
+).toSorted();
+
+const allIconNamesSet = new Set(allIconNamesSorted);
+
+/**
+ * Storage prefix for Lucide icon references in `iconUrl` fields.
+ * A stored value like `lucide:plane` preserves the symbolic icon name so
+ * the picker can highlight the current selection and config/export files
+ * can carry human-readable icon references.
+ */
+export const LUCIDE_PREFIX = "lucide:";
+
+/** True if `iconUrl` is a stored Lucide reference. */
+export function isLucideIconRef(
+ iconUrl: string | undefined,
+): iconUrl is `lucide:${string}` {
+ return !!iconUrl && iconUrl.startsWith(LUCIDE_PREFIX);
+}
+
+/** True if `name` matches a known Lucide icon. */
+export function isValidLucideIconName(name: string): name is IconName {
+ return !!name && allIconNamesSet.has(name);
+}
+
+/** Extract the icon name from a `lucide:` reference, or null. */
+export function getLucideName(iconUrl: string | undefined): string | null {
+ if (!isLucideIconRef(iconUrl)) return null;
+ return iconUrl.slice(LUCIDE_PREFIX.length);
+}
+
+/** Build a `lucide:` reference for storage. */
+export function toLucideIconRef(iconName: string): string {
+ return `${LUCIDE_PREFIX}${iconName}`;
+}
+
+/**
+ * Returns the raw SVG markup for a Lucide icon by name, or null if unknown.
+ * Used by render pipelines (e.g., Cytoscape) that need the SVG text rather
+ * than a data URI.
+ */
+export async function getLucideSvgString(
+ iconName: string,
+): Promise {
+ if (!isValidLucideIconName(iconName)) {
+ return null;
+ }
+ try {
+ const { default: Icon } = await dynamicIconImports[iconName]();
+ return renderToStaticMarkup(createElement(Icon));
+ } catch {
+ return null;
+ }
+}