@artcom/react-debug-clickables

A React hook that outlines and labels every clickable element on the page while a debug flag is active - handy for exhibit/kiosk apps where visitors never see a cursor and it's otherwise hard to tell what's tappable.

Installation

npm install @artcom/react-debug-clickables

Usage

import { useDebugClickables } from "@artcom/react-debug-clickables"

function App() {
  const debugMode = useSomeAppSpecificDebugFlag()
  useDebugClickables(debugMode)

  return <YourApp />
}

Whenever active is true, every element the heuristic below recognizes as clickable gets a red/lime outline and a small label showing its accessible name. Toggling active is entirely up to the caller - a query parameter, a keyboard shortcut, feature flag, or an MQTT topic all work.

useDebugClickables(active, options?)

| Option | Type | Default | Description | | ------ | ----------------- | ---------------- | ---------------------------------------- | | root | Element \| Document | document.body | Subtree to scan for clickable elements. |

Detecting clickable elements

An element is flagged as clickable when it:

• is a native interactive tag (button, a[href], input, select, textarea, summary, ...),
• has an interactive ARIA role (role="button", "link", "checkbox", ...),
• has an onclick attribute, a native element.onclick handler, or a non-negative tabindex, or
• is styled with cursor: pointer that isn't just inherited from a clickable ancestor - this is what catches elements made clickable purely through a framework event handler (e.g. React's onClick, which never sets the native element.onclick property).

Disabled elements (disabled, aria-disabled="true") are never flagged.

The cursor: pointer heuristic is best-effort. Override it per element with data-debug-clickable="true" (force include) or data-debug-clickable="false" (force exclude).

No layout shift

The debug outline is drawn with outline and box-shadow, never border. Both are pure paint effects excluded from the box model, so turning debug mode on can never resize an element or reflow the page - unlike border, which changes an element's rendered size (or, with box-sizing: border-box, still eats into its content width) and can shift flex/grid layouts or wrap text. This matters most for apps built on floating/auto layout rather than fixed positioning, where a border-based overlay would visibly move things around.

@artcom/react-debug-clickables/mqtt

A convenience wrapper for apps already using @artcom/mqtt-topping-react, which toggles debug mode from an MQTT topic:

import { useMqttDebugClickables } from "@artcom/react-debug-clickables/mqtt"

function App() {
  useMqttDebugClickables("your-app/debug")

  return <YourApp />
}

topic has no default - it's always supplied by the calling app, so this package never bakes in any app- or client-specific topic name. @artcom/mqtt-topping-react is an optional peer dependency, only required if you import from this /mqtt entry point; it's not needed for the core useDebugClickables hook.

Development

npm install
npm test
npm run lint
npm run build