@runilib/react-walkit

Part of the runilib ecosystem — React & React Native libraries that share the same API on web and native.

This repository is mirrored from the runilib monorepo. Active development happens in the monorepo. Open or in-progress work may appear here as automated draft PRs for visibility, and issues opened here can be mirrored back to the monorepo.

Cross-platform onboarding tours, guided walkthroughs, and standalone tooltips for React and React Native.

@runilib/react-walkit is the onboarding & tooltips package of runilib. It helps you highlight UI, attach contextual popovers, and run guided tours or simple feature tooltips with the same API across web and native, including cross-page and cross-screen flows.

Full documentation: https://runilib.dev/libraries/walkit

Demo Previews

React Web walkthrough

Desktop preview of the default Walkit onboarding flow on React web. Click the animation to open the full video.

React Web tooltip

Desktop preview of the standalone Tooltip component on React web. Click the animation to open the full video.

React Native previews

Side-by-side mobile previews of the full onboarding flow and the standalone tooltip primitive on React Native. Click an animation to open the full video.

What It Solves

• Product tours and onboarding flows
• Standalone tooltips for contextual help and feature announcements
• Spotlight + tooltip guidance around real UI elements
• One API for React web and React Native
• Cross-page and cross-screen navigation with a shared flow model

Install

npm install @runilib/react-walkit

React Native also needs react-native-svg.

Quick Example

import { WalkitProvider, WalkitStep, useWalkit } from '@runilib/react-walkit';

function StartTourButton() {
  const { start } = useWalkit();

  return <button onClick={() => start()}>Start tour</button>;
}

export function App() {
  return (
    <WalkitProvider>
      <WalkitStep
        id="search"
        sequence={1}
        title="Search"
        content="Use this field to quickly find projects and tasks."
      >
        <input placeholder="Search..." />
      </WalkitStep>

      <StartTourButton />
    </WalkitProvider>
  );
}

Accessible Tooltips

Use a stable id when the tooltip describes a control that users may revisit. On web, Tooltip applies that id to the rendered tooltip surface and links the trigger wrapper with aria-describedby while the tooltip is visible by default. Use ariaDescribedBy="always" when the trigger should expose the description before the tooltip is opened.

import { Tooltip } from '@runilib/react-walkit';

export function BillingHelp() {
  return (
    <Tooltip
      id="billing-help"
      ariaLabel="Billing help"
      closeOnEscape
      openOnPress
      content="This appears on your invoice."
    >
      <button type="button">?</button>
    </Tooltip>
  );
}

• Prefer openOnPress for keyboard, touch, TalkBack, and VoiceOver parity. Hover-only tooltips are useful as a visual enhancement, but they should not be the only way to reach important information.
• Keep descriptive tooltips non-interactive. If the content contains links, buttons, form fields, or other focusable controls, set interactive so web uses dialog semantics instead of role="tooltip".
• Leave closeOnEscape enabled for web unless the tooltip is fully controlled by your own state. Escape closes the open tooltip even when focus has moved away from the trigger.
• For custom triggers, make the trigger itself focusable and named. Use a native <button> on web or a named pressable control on React Native whenever possible.
• On React Native, text content or ariaLabel is announced when the tooltip opens, and press triggers expose expansion state plus an accessibility hint when ariaDescribedBy is active.

Step-level Outside Dismissal

stopOnOutsideClick can be configured globally on WalkitProvider and overridden by a single WalkitStep. The current step override wins when it is defined; otherwise Walkit uses the provider value.

<WalkitProvider stopOnOutsideClick>
  <WalkitStep
    id="danger-zone"
    sequence={3}
    title="Review this action"
    content="Choose Next, Back, or Skip explicitly before leaving this step."
    stopOnOutsideClick={false}
  >
    <button type="button">Delete workspace</button>
  </WalkitStep>
</WalkitProvider>

Testing Accessibility

• Web keyboard: tab to the trigger, open with Enter or Space, close with Escape, and confirm focus remains usable.
• Web ARIA: verify aria-describedby points to the tooltip id; use role="tooltip" for descriptive content and interactive for dialog-like content.
• Web screen readers: test with VoiceOver, NVDA, or JAWS and confirm the trigger name plus description are announced clearly.
• Native screen readers: test TalkBack and VoiceOver; focus the trigger, activate it, and confirm content or ariaLabel is announced.
• Native custom content: give every actionable Pressable an accessibilityRole and a clear accessibilityLabel.
• Automated checks: assert roles, ids, aria-describedby, Escape dismissal, closeOnEscape={false}, and per-step stopOnOutsideClick fallback/override behavior with Testing Library.

Documentation

• Docs and guides: https://runilib.dev/libraries/walkit

Contributing

Bug reports and feature requests are welcome in this repo's issues. They are mirrored to the monorepo where the work happens.

If you want to change the package itself, work from the monorepo and use this flow before opening a PR:

1. Make the code, docs, and test updates in packages/react-walkit.
2. Run yarn changeset from the monorepo root and include @runilib/react-walkit.
3. Run yarn check:fix, yarn typecheck, and yarn test.
4. Optionally run npm run --prefix packages/react-walkit prepublishOnly for an extra publish-safety check.
5. Open the PR against the monorepo main branch. After merge, GitHub creates a package-specific release PR so this library can be published independently from the others.

Looking for something to start with? Browse good first issues.

See CONTRIBUTING.md for the full guide.