Add hoverOnly option to ClickToEditOptions

Allow click-to-edit to be conditionally enabled only on devices that
support hover (non-touch devices), using window.matchMedia('(hover: hover)').
This helps avoid overlay interference on touch devices.

Author: stefanoverna

docs/content-link.md

@@ -200,12 +200,26 @@ There are two ways to enable click-to-edit mode:
 <ContentLink enableClickToEdit={true} />
 ```
 
-Or with scroll-to-nearest option:
+Or with additional options:
 
 ```jsx
+// Scroll to nearest editable element if none is visible
 <ContentLink enableClickToEdit={{ scrollToNearestTarget: true }} />
+
+// Only enable on devices with hover capability (non-touch)
+<ContentLink enableClickToEdit={{ hoverOnly: true }} />
+
+// Combine both options
+<ContentLink enableClickToEdit={{ hoverOnly: true, scrollToNearestTarget: true }} />
 ```
 
+**Available options (`ClickToEditOptions`):**
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `scrollToNearestTarget` | `boolean` | `false` | Automatically scroll to the nearest editable element if none is currently visible in the viewport |
+| `hoverOnly` | `boolean` | `false` | Only enable click-to-edit on devices that support hover (non-touch). Uses `window.matchMedia('(hover: hover)')` to detect hover capability. On touch-only devices, users can still toggle manually with Alt/Option key |
+
 This enables click-to-edit overlays immediately and keeps them visible.
 
 ### 2. Via keyboard shortcut (temporary)
@@ -245,7 +259,7 @@ The `<ContentLink />` component accepts the following props:
 | ------------------- | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `onNavigateTo`      | `(path: string) => void`                  | -       | Callback when [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews) requests navigation to a different page |
 | `currentPath`       | `string`                                  | -       | Current pathname to sync with [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews)                         |
-| `enableClickToEdit` | `true \| { scrollToNearestTarget: true }` | -       | Enable click-to-edit overlays on mount. Pass `true` or an object with options. If undefined, click-to-edit is disabled                                 |
+| `enableClickToEdit` | `boolean \| ClickToEditOptions` | -       | Enable click-to-edit overlays on mount. Pass `true` or an object with options. If `false`/`undefined`, click-to-edit is disabled (use Alt/Option key to toggle) |
 | `stripStega`        | `boolean`                                 | -       | Whether to strip stega encoding from text nodes after stamping                                                                                         |
 | `root`              | `React.RefObject<HTMLElement>`            | -       | Ref to limit scanning to this root element instead of the entire document                                                                              |
 

src/ContentLink/index.tsx

@@ -2,15 +2,30 @@
 
 import { useEffect } from 'react';
 import {
+  type ClickToEditOptions,
   type UseContentLinkOptions,
   useContentLink,
 } from '../useContentLink/index.js';
 
 export type ContentLinkProps = Omit<UseContentLinkOptions, 'enabled'> & {
   /** Current pathname to sync with Web Previews plugin */
   currentPath?: string;
-  /** Enable click-to-edit on mount. Pass true for default behavior or an object with scrollToNearestTarget. If undefined or false, click-to-edit is disabled. */
-  enableClickToEdit?: boolean | { scrollToNearestTarget: true };
+  /**
+   * Whether to enable click-to-edit overlays on mount, or options to configure them.
+   *
+   * - `true`: Enable click-to-edit mode immediately
+   * - `{ scrollToNearestTarget: true }`: Enable and scroll to nearest editable if none visible
+   * - `{ hoverOnly: true }`: Only enable on devices with hover capability (non-touch)
+   * - `false`/`undefined`: Don't enable automatically (use Alt/Option key to toggle)
+   *
+   * @example
+   * ```tsx
+   * <ContentLink enableClickToEdit={true} />
+   * <ContentLink enableClickToEdit={{ scrollToNearestTarget: true }} />
+   * <ContentLink enableClickToEdit={{ hoverOnly: true, scrollToNearestTarget: true }} />
+   * ```
+   */
+  enableClickToEdit?: boolean | ClickToEditOptions;
   /** Whether to strip stega encoding from text nodes after stamping. */
   stripStega?: boolean;
 };

src/useContentLink/index.ts

@@ -29,11 +29,36 @@ export type UseContentLinkOptions = {
   root?: React.RefObject<HTMLElement>;
 };
 
+export interface ClickToEditOptions {
+  /**
+   * Whether to automatically scroll to the nearest editable element if none
+   * is currently visible in the viewport when click-to-edit mode is enabled.
+   *
+   * @default false
+   */
+  scrollToNearestTarget?: boolean;
+
+  /**
+   * Only enable click-to-edit on devices that support hover (i.e., non-touch devices).
+   * Uses `window.matchMedia('(hover: hover)')` to detect hover capability.
+   *
+   * This is useful to avoid showing overlays on touch devices where they may
+   * interfere with normal scrolling and tapping behavior.
+   *
+   * When set to `true` on a touch-only device, click-to-edit will not be
+   * automatically enabled, but users can still toggle it manually using
+   * the Alt/Option key.
+   *
+   * @default false
+   */
+  hoverOnly?: boolean;
+}
+
 export type UseContentLinkResult = {
   /** The controller instance, or null if disabled */
   controller: Controller | null;
   /** Enable click-to-edit overlays */
-  enableClickToEdit: (options?: { scrollToNearestTarget: boolean }) => void;
+  enableClickToEdit: (options?: ClickToEditOptions) => void;
   /** Disable click-to-edit overlays */
   disableClickToEdit: () => void;
   /** Check if click-to-edit is enabled */
@@ -118,12 +143,9 @@ export function useContentLink(
   }, [enabled, root]);
 
   // Stable method references that call through to the controller
-  const enableClickToEdit = useCallback(
-    (opts?: { scrollToNearestTarget: boolean }) => {
-      controllerRef.current?.enableClickToEdit(opts);
-    },
-    [],
-  );
+  const enableClickToEdit = useCallback((opts?: ClickToEditOptions) => {
+    controllerRef.current?.enableClickToEdit(opts);
+  }, []);
 
   const disableClickToEdit = useCallback(() => {
     controllerRef.current?.disableClickToEdit();