@wayfinder/react

React helpers for @wayfinder/core that let you target elements reliably even when class names are obfuscated by CSS Modules, styled-components, Emotion, or build minifiers.

Installation

npm install @wayfinder/react @wayfinder/core @floating-ui/dom

The problem

When you use CSS Modules or a CSS-in-JS library, class names become unstable across builds:

// Source
<button className={styles.createBtn}>New Project</button>

// After build
<button class="createBtn_xK2p9">New Project</button>

Using target: '.createBtn' in a Wayfinder step will break after the next build. This package solves that by writing a stable data-tour attribute that is never touched by any build tool.

useTourTarget hook

Attach the hook to any element. It writes data-tour="<id>" on mount and removes it on unmount.

import { useTourTarget } from '@wayfinder/react';
import { Wayfinder, tourId } from '@wayfinder/core';

function CreateButton() {
  const ref = useTourTarget('create-btn');
  return <button ref={ref}>New Project</button>;
}

const tour = new Wayfinder({
  steps: [
    {
      id: 'create-btn',
      target: tourId('create-btn'), // '[data-tour="create-btn"]'
      title: 'Create a new project',
      description: 'Click here to get started.',
    },
  ],
});

TourTarget component

Use TourTarget to wrap a third-party component you cannot modify:

import { TourTarget } from '@wayfinder/react';

<TourTarget id="create-btn">
  <ThirdPartyButton>New Project</ThirdPartyButton>
</TourTarget>

This renders a display: contents span (invisible in layout) with the data-tour attribute attached.

Custom attribute name

Both the hook and the component accept an attribute prop/option if data-tour conflicts with another library:

const ref = useTourTarget('create-btn', 'data-wf-target');

// Pair it with a matching tourAttribute in WayfinderConfig:
new Wayfinder({ tourAttribute: 'data-wf-target', steps: [...] });