Support custom cursors (#503) (#504)

bvaughn · web-flow · commit 9b69a44a1f32 · 2025-07-29T20:18:35.000-04:00
diff --git a/packages/react-resizable-panels-website/index.tsx b/packages/react-resizable-panels-website/index.tsx
@@ -1,19 +1,20 @@
-import { StrictMode, useEffect } from "react";
+import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { createBrowserRouter, RouterProvider } from "react-router-dom";
 
+import EndToEndTestingRoute from "./src/routes/EndToEndTesting";
 import HomeRoute from "./src/routes/Home";
+import CollapsibleExampleRoute from "./src/routes/examples/Collapsible";
 import ConditionalExampleRoute from "./src/routes/examples/Conditional";
+import CustomCursorExampleRoute from "./src/routes/examples/CustomCursorExampleRoute";
 import ExternalPersistenceExampleRoute from "./src/routes/examples/ExternalPersistence";
 import HorizontalExampleRoute from "./src/routes/examples/Horizontal";
 import ImperativePanelApiExampleRoute from "./src/routes/examples/ImperativePanelApi";
 import ImperativePanelGroupApiExampleRoute from "./src/routes/examples/ImperativePanelGroupApi";
 import NestedExampleRoute from "./src/routes/examples/Nested";
 import OverflowExampleRoute from "./src/routes/examples/Overflow";
 import PersistenceExampleRoute from "./src/routes/examples/Persistence";
-import CollapsibleExampleRoute from "./src/routes/examples/Collapsible";
 import VerticalExampleRoute from "./src/routes/examples/Vertical";
-import EndToEndTestingRoute from "./src/routes/EndToEndTesting";
 import IframeRoute from "./src/routes/iframe";
 
 const router = createBrowserRouter([
@@ -25,6 +26,10 @@ const router = createBrowserRouter([
     path: "/examples/conditional",
     element: <ConditionalExampleRoute />,
   },
+  {
+    path: "/examples/custom-cursor",
+    element: <CustomCursorExampleRoute />,
+  },
   {
     path: "/examples/external-persistence",
     element: <ExternalPersistenceExampleRoute />,
diff --git a/packages/react-resizable-panels-website/src/routes/Home/index.tsx b/packages/react-resizable-panels-website/src/routes/Home/index.tsx
@@ -14,6 +14,7 @@ const LINKS = [
   { path: "collapsible", title: "Collapsible panels" },
   { path: "conditional", title: "Conditional panels" },
   { path: "external-persistence", title: "External persistence" },
+  { path: "custom-cursor", title: "Custom cursor" },
   { path: "imperative-panel-api", title: "Imperative Panel API" },
   { path: "imperative-panel-group-api", title: "Imperative PanelGroup API" },
 ];
diff --git a/packages/react-resizable-panels-website/src/routes/examples/CustomCursorExampleRoute.tsx b/packages/react-resizable-panels-website/src/routes/examples/CustomCursorExampleRoute.tsx
@@ -0,0 +1,77 @@
+import {
+  CustomCursorStyleConfig,
+  customizeGlobalCursorStyles,
+  Panel,
+  PanelGroup,
+} from "react-resizable-panels";
+
+import { ResizeHandle } from "../../components/ResizeHandle";
+
+import { useLayoutEffect } from "react";
+import Example from "./Example";
+import styles from "./shared.module.css";
+
+export default function CustomCursorExampleRoute() {
+  return (
+    <Example
+      code={CODE}
+      exampleNode={<Content />}
+      headerNode={
+        <>
+          <p>
+            By default, this library manages cursor styles in response to user
+            input. You <em>can</em> override the default cursor for advanced use
+            cases, though it's generally not recommended.
+          </p>
+        </>
+      }
+      title="Custom cursor"
+    />
+  );
+}
+
+function Content() {
+  useLayoutEffect(() => {
+    function customCursor({ isPointerDown }: CustomCursorStyleConfig) {
+      return isPointerDown ? "grabbing" : "grab";
+    }
+
+    customizeGlobalCursorStyles(customCursor);
+    return () => {
+      customizeGlobalCursorStyles(null);
+    };
+  }, []);
+
+  return (
+    <div className={styles.PanelGroupWrapper}>
+      <PanelGroup className={styles.PanelGroup} direction="horizontal">
+        <Panel className={styles.PanelRow} minSize={10}>
+          <div className={styles.Centered}>left</div>
+        </Panel>
+        <ResizeHandle className={styles.ResizeHandle} />
+        <Panel className={styles.PanelRow} minSize={10}>
+          <div className={styles.Centered}>right</div>
+        </Panel>
+      </PanelGroup>
+    </div>
+  );
+}
+
+const CODE = `
+import { customizeGlobalCursorStyles, type CustomCursorStyleConfig } from "react-resizable-panels";
+
+function Example() {
+  useLayoutEffect(() => {
+    function customCursor({ isPointerDown }: CustomCursorStyleConfig) {
+      return isPointerDown ? "grabbing" : "grab";
+    }
+
+    customizeGlobalCursorStyles(customCursor);
+    return () => {
+      customizeGlobalCursorStyles(null);
+    };
+  }, []);
+
+  // ...
+}
+`;
diff --git a/packages/react-resizable-panels-website/tests/CursorStyle.spec.ts b/packages/react-resizable-panels-website/tests/CursorStyle.spec.ts
@@ -60,37 +60,53 @@ test.describe("cursor style", () => {
     await dragResizeTo(
       page,
       "first-panel",
-      { size: 15, expectedCursor: getCursorStyle("horizontal", 0) },
+      { size: 15, expectedCursor: getCursorStyle("horizontal", 0, false) },
       {
         size: 5,
-        expectedCursor: getCursorStyle("horizontal", EXCEEDED_HORIZONTAL_MIN),
+        expectedCursor: getCursorStyle(
+          "horizontal",
+          EXCEEDED_HORIZONTAL_MIN,
+          false
+        ),
       },
-      { size: 15, expectedCursor: getCursorStyle("horizontal", 0) },
-      { size: 85, expectedCursor: getCursorStyle("horizontal", 0) },
+      { size: 15, expectedCursor: getCursorStyle("horizontal", 0, false) },
+      { size: 85, expectedCursor: getCursorStyle("horizontal", 0, false) },
       {
         size: 95,
-        expectedCursor: getCursorStyle("horizontal", EXCEEDED_HORIZONTAL_MAX),
+        expectedCursor: getCursorStyle(
+          "horizontal",
+          EXCEEDED_HORIZONTAL_MAX,
+          false
+        ),
       },
-      { size: 85, expectedCursor: getCursorStyle("horizontal", 0) }
+      { size: 85, expectedCursor: getCursorStyle("horizontal", 0, false) }
     );
 
     await openPage(page, "vertical");
 
     await dragResizeTo(
       page,
       "first-panel",
-      { size: 15, expectedCursor: getCursorStyle("vertical", 0) },
+      { size: 15, expectedCursor: getCursorStyle("vertical", 0, false) },
       {
         size: 5,
-        expectedCursor: getCursorStyle("vertical", EXCEEDED_VERTICAL_MIN),
+        expectedCursor: getCursorStyle(
+          "vertical",
+          EXCEEDED_VERTICAL_MIN,
+          false
+        ),
       },
-      { size: 15, expectedCursor: getCursorStyle("vertical", 0) },
-      { size: 85, expectedCursor: getCursorStyle("vertical", 0) },
+      { size: 15, expectedCursor: getCursorStyle("vertical", 0, false) },
+      { size: 85, expectedCursor: getCursorStyle("vertical", 0, false) },
       {
         size: 95,
-        expectedCursor: getCursorStyle("vertical", EXCEEDED_VERTICAL_MAX),
+        expectedCursor: getCursorStyle(
+          "vertical",
+          EXCEEDED_VERTICAL_MAX,
+          false
+        ),
       },
-      { size: 85, expectedCursor: getCursorStyle("vertical", 0) }
+      { size: 85, expectedCursor: getCursorStyle("vertical", 0, false) }
     );
   });
 
@@ -143,59 +159,79 @@ test.describe("cursor style", () => {
       "outer-group",
       ["horizontal-handle", "vertical-handle"],
       {
-        expectedCursor: getCursorStyle("intersection", 0),
+        expectedCursor: getCursorStyle("intersection", 0, false),
         sizeX: 0.4,
         sizeY: 0.4,
       },
       {
-        expectedCursor: getCursorStyle("intersection", 0),
+        expectedCursor: getCursorStyle("intersection", 0, false),
         sizeX: 0.6,
         sizeY: 0.6,
       },
       {
-        expectedCursor: getCursorStyle("intersection", EXCEEDED_HORIZONTAL_MIN),
+        expectedCursor: getCursorStyle(
+          "intersection",
+          EXCEEDED_HORIZONTAL_MIN,
+          false
+        ),
         sizeX: 0.1,
       },
       {
-        expectedCursor: getCursorStyle("intersection", EXCEEDED_HORIZONTAL_MAX),
+        expectedCursor: getCursorStyle(
+          "intersection",
+          EXCEEDED_HORIZONTAL_MAX,
+          false
+        ),
         sizeX: 0.9,
       },
       {
-        expectedCursor: getCursorStyle("intersection", EXCEEDED_VERTICAL_MIN),
+        expectedCursor: getCursorStyle(
+          "intersection",
+          EXCEEDED_VERTICAL_MIN,
+          false
+        ),
         sizeY: 0.1,
       },
       {
-        expectedCursor: getCursorStyle("intersection", EXCEEDED_VERTICAL_MAX),
+        expectedCursor: getCursorStyle(
+          "intersection",
+          EXCEEDED_VERTICAL_MAX,
+          false
+        ),
         sizeY: 0.9,
       },
       {
         expectedCursor: getCursorStyle(
           "intersection",
-          EXCEEDED_HORIZONTAL_MIN | EXCEEDED_VERTICAL_MIN
+          EXCEEDED_HORIZONTAL_MIN | EXCEEDED_VERTICAL_MIN,
+          false
         ),
         sizeX: 0.1,
         sizeY: 0.1,
       },
       {
         expectedCursor: getCursorStyle(
           "intersection",
-          EXCEEDED_HORIZONTAL_MIN | EXCEEDED_VERTICAL_MAX
+          EXCEEDED_HORIZONTAL_MIN | EXCEEDED_VERTICAL_MAX,
+          false
         ),
         sizeX: 0.1,
         sizeY: 0.9,
       },
       {
         expectedCursor: getCursorStyle(
           "intersection",
-          EXCEEDED_HORIZONTAL_MAX | EXCEEDED_VERTICAL_MIN
+          EXCEEDED_HORIZONTAL_MAX | EXCEEDED_VERTICAL_MIN,
+          false
         ),
         sizeX: 0.9,
         sizeY: 0.1,
       },
       {
         expectedCursor: getCursorStyle(
           "intersection",
-          EXCEEDED_HORIZONTAL_MAX | EXCEEDED_VERTICAL_MAX
+          EXCEEDED_HORIZONTAL_MAX | EXCEEDED_VERTICAL_MAX,
+          false
         ),
         sizeX: 0.9,
         sizeY: 0.9,
diff --git a/packages/react-resizable-panels/README.md b/packages/react-resizable-panels/README.md
@@ -247,3 +247,15 @@ import { disableGlobalCursorStyles } from "react-resizable-panels";
 
 disableGlobalCursorStyles();
 ```
+
+#### How can I override the global cursor styles?
+
+```js
+import { customizeGlobalCursorStyles, type CustomCursorStyleConfig } from "react-resizable-panels";
+
+function customCursor({ isPointerDown }: CustomCursorStyleConfig) {
+  return isPointerDown ? "grabbing" : "grab";
+}
+
+customizeGlobalCursorStyles(customCursor);
+```
diff --git a/packages/react-resizable-panels/src/PanelResizeHandleRegistry.ts b/packages/react-resizable-panels/src/PanelResizeHandleRegistry.ts
@@ -104,6 +104,9 @@ function handlePointerDown(event: PointerEvent) {
   if (intersectingHandles.length > 0) {
     updateResizeHandlerStates("down", event);
 
+    // Update cursor based on return value(s) from active handles
+    updateCursor();
+
     event.preventDefault();
 
     if (!isWithinResizeHandle(target as HTMLElement)) {
@@ -290,11 +293,11 @@ function updateCursor() {
   });
 
   if (intersectsHorizontal && intersectsVertical) {
-    setGlobalCursorStyle("intersection", constraintFlags);
+    setGlobalCursorStyle("intersection", constraintFlags, isPointerDown);
   } else if (intersectsHorizontal) {
-    setGlobalCursorStyle("horizontal", constraintFlags);
+    setGlobalCursorStyle("horizontal", constraintFlags, isPointerDown);
   } else if (intersectsVertical) {
-    setGlobalCursorStyle("vertical", constraintFlags);
+    setGlobalCursorStyle("vertical", constraintFlags, isPointerDown);
   } else {
     resetGlobalCursorStyle();
   }
diff --git a/packages/react-resizable-panels/src/index.ts b/packages/react-resizable-panels/src/index.ts
@@ -6,6 +6,7 @@ import { usePanelGroupContext } from "./hooks/usePanelGroupContext";
 import { assert } from "./utils/assert";
 import { setNonce } from "./utils/csp";
 import {
+  customizeGlobalCursorStyles,
   disableGlobalCursorStyles,
   enableGlobalCursorStyles,
 } from "./utils/cursor";
@@ -37,6 +38,7 @@ import type {
   PanelResizeHandleProps,
 } from "./PanelResizeHandle";
 import type { PointerHitAreaMargins } from "./PanelResizeHandleRegistry";
+import type { CustomCursorStyleConfig } from "./utils/cursor";
 
 export {
   // TypeScript types
@@ -76,10 +78,14 @@ export {
   getResizeHandlePanelIds,
 
   // Styles and CSP (see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce)
-  enableGlobalCursorStyles,
-  disableGlobalCursorStyles,
   setNonce,
 
+  // Global cursor configuration
+  customizeGlobalCursorStyles,
+  disableGlobalCursorStyles,
+  enableGlobalCursorStyles,
+  CustomCursorStyleConfig,
+
   // Data attributes (primarily intended for e2e testing)
   DATA_ATTRIBUTES,
 };
diff --git a/packages/react-resizable-panels/src/utils/cursor.ts b/packages/react-resizable-panels/src/utils/cursor.ts
