Package Exports

guideme-js
guideme-js/dist/index.js
guideme-js/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (guideme-js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

User Guide Hook Documentation

Introduction

A React hook package designed to create interactive user guides and onboarding tutorials with customizable tooltips and overlays.

Installation

npm i guideme-js

Required peer dependencies:

{
  "react": "^19.0.0",
  "react-dom": "^19.0.0"
}

Basic Usage

1. Provider Setup

Wrap your application with the UserGuideProvider in main.tsx:

import { UserGuideProvider } from "guideme-js";
import "guideme-js/style.css";

function App() {
  return (
    <UserGuideProvider>
      <YourApp />
    </UserGuideProvider>
  );
}

You can add some props to your provider

import { UserGuideProvider } from "guideme-js";
import "guideme-js/style.css";

function App() {
  return (
    <UserGuideProvider closeOnClickOut withIndicator dir="rtl">
      <YourApp />
    </UserGuideProvider>
  );
}

2. Creating Guide Steps

Use the ready component:

import { useUserGuide, UserGuideStepWrapper } from "guideme-js";
import "guideme-js/style.css";

function MyComponent() {
  return (
    <UserGuideStepWrapper
      step={{
        title: "Settings",
        description: "Customize your workspace preferences.",
        subTitle: "STEP 4",
        index: 3,
        position: "bottom-right",
      }}
      className="rounded-lg p-2"
    >
      <button
        className={`bg-transparent  p-2 rounded-lg hover:bg-gray-100 transition-colors `}
      >
        <Settings size={20} />
      </button>
    </UserGuideStepWrapper>
  );
}

Use the hook in your components for more flexibility and customization:

import { useUserGuide } from 'guideme-js';
import "guideme-js/style.css"

function MyComponent() {
  const { getRef, setIsActiveGuide, isStepActive } = useUserGuide<HTMLDivElement>();

  return (
    <div>
      <button
        ref={getRef({
          index: 0,
          subTitle: "STEP 1",
          title: "Welcome!",
          description: "lorem ipsum dolor sit amet con etras  et sapiente et sap.",
          position: "bottom-left"
        })}
        className={isStepActive(0)}
        onClick={() => setIsActiveGuide(true)}
      >
        Start Guide
      </button>
    </div>
  );
}

API Reference

UserGuideProvider

The context provider for the guide functionality.

Props:

Name	Type	Default	Description
dir	`ltr, rtl`	`rtl`	Controls tooltip directionality. RTL mode is optimized for Arabic and other RTL languages.
closeOnClickOut	`boolean`	`false`	Enables tooltip dismissal when clicking outside its bounds.
withIndicator	`boolean`	`false`	Shows a small arrow pointing to the tooltip's reference element.
children	`ReactNode`	`required`	Child components

1. Direction (dir) Property Example

The dir prop controls tooltip text direction and positioning.

// RTL Example (Arabic)
<UserGuideProvider dir="rtl">
  <YourApp />
</UserGuideProvider>

2.Close on Click Outside (closeOnClickOut) Example

Enable closing tooltips by clicking outside their bounds.

<UserGuideProvider closeOnClickOut>
  <YourApp />
</UserGuideProvider>

3.Indicator Arrow (withIndicator) Example

Add a visual arrow pointing to the referenced element.

<UserGuideProvider withIndicator>
  <YourApp />
</UserGuideProvider>

4.Indicator Arrow (withIndicator) Example

Or You can comibne them togher to get all functionality

<UserGuideProvider closeOnClickOut withIndicator dir="rtl">
  <YourApp />
</UserGuideProvider>

useUserGuide Hook

The main hook for implementing guide functionality.

Returns:

Name	Type	Description
getRef	`Function`	Creates refs for guide steps
setIsActiveGuide	`(active: boolean) => void`	Controls guide visibility
isStepActive	`(index: number) => string`	Checks if a step is active

StepWrapper component

The main hook for implementing guide functionality.

Returns:

Name	Type	Description
children	`ReactNode`	Child components
step	`Step`	Step information
className	`string`	className

Step Configuration

interface Step {
  index: number; // The step's sequential order in the guide
  title: string; // The main heading summarizing the step
  subTitle: string; // A secondary heading providing additional context
  description: string; // A detailed explanation of the step's purpose
  imgUrl?: string; // (Optional) URL for an illustration image representing the step
  position: Position; // Specifies the tooltip or modal's display position
}

the perspective is determined by the main element position
type Position =
  | "top-left" // Tooltip positioned at the top-left
  | "top-center" // Tooltip centered at the top
  | "top-right" // Tooltip positioned at the top-right
  | "left-center" // Tooltip centered on the left side
  | "right-center" // Tooltip centered on the right side
  | "bottom-left" // Tooltip positioned at the bottom-left
  | "bottom-right" // Tooltip positioned at the bottom-right
  | "bottom-center" // Tooltip centered at the bottom
  | "bottom-left-full" // Tooltip fully aligned at the bottom-left
  | "bottom-right-full" // Tooltip fully aligned at the bottom-right
  | "top-left-full" // Tooltip fully aligned at the top-left
  | "top-right-full"; // Tooltip fully aligned at the top-right

Components

UserGuideModal

Modal component that displays step information.

UserGuideOverlay

Overlay component that highlights the active element.

Advanced Usage

import "guideme-js/style.css"

function CustomStyledGuide() {
  const { getRef } = useUserGuide<HTMLDivElement>();

  return (
    <button
      ref={getRef({
        index: 0,
        subTitle: "STEP 1",
        title: "Welcome!",
        description: "lorem ipsum dolor sit amet con etras  et sapiente et sap.",
        position: "bottom-left"
      })}
    >
      Custom Step
    </button>
  );
}

Multi-Step Guide Example

Note imageUrl is optional

import "guideme-js/style.css"

function MultiStepGuide() {
  const { getRef, setIsActiveGuide } = useUserGuide<HTMLDivElement>();

  return (
    <div>
      <button
        ref={getRef({ index: 0, title: "Step 1", decription : "description 1", imageUrl: "url/img/step1" subTitle: "Step 1" })}
      >
        First Step
      </button>
      <div
        ref={getRef({ index: 1, title: "Step 2", decription : "description 2", imageUrl: "url/img/step2" subTitle: "Step 2" })}
      >
        Second Step
      </div>
      <span
        ref={getRef({ index: 2, title: "Final Step", decription : "description 3", imageUrl: "url/img/step3" subTitle: "Step 3" })}
      >
        Last Step
      </span>
    </div>
  );
}

TypeScript Support

The package includes full TypeScript support. Specify the element type when using the hook:

const { getRef } = useUserGuide<HTMLButtonElement>();

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT