GoGuide

GoGuide is an interactive walkthrough and tour guide component for React applications, created by GoStack.

It provides a customized overlay with smooth backdrop animations (using Framer Motion) and customizable popovers to guide users step-by-step through your application interface.

Installation

Install the package via npm, yarn, or pnpm. Ensure that you have the required peer dependencies installed:

npm install goguide

Peer Dependencies

GoGuide expects the following dependencies to be present in the host project:

• react >= 19.2.0
• react-dom >= 19.2.0
• framer-motion >= 12.23.26
• lucide-react >= 0.562.0
• react-i18next >= 16.5.0

Usage

GoGuide is fully self-contained. You do not need to configure any special bundler aliases or paths.

1. Set Up the Provider

Define your tour configurations (of type Record<string, Tour>) in your host application and wrap your application in the TourProvider component, passing the configurations via the config prop.

import React from "react";
import { TourProvider, Tour } from "goguide";

// Define your tours config here
const toursConfig: Record<string, Tour> = {
  "dashboard-main": {
    id: "dashboard-main",
    steps: [
      {
        selector: "#dashboard-header-container",
        titleKey: "shared:tour.dashboard.header.title",
        contentKey: "shared:tour.dashboard.header.content",
        placement: "bottom",
      }
    ]
  }
};

export default function App() {
  return (
    <TourProvider config={toursConfig}>
      <MyApplication />
    </TourProvider>
  );
}

2. Include the Overlay

Render the TourOverlay component at the root level of your application (under the TourProvider), passing your custom translation function t and reading direction option isRTL.

import React from "react";
import { TourOverlay } from "goguide";
import { useTranslation } from "react-i18next";

export function MyApplication() {
  const { t, i18n } = useTranslation("shared");
  const isRTL = i18n.language === "ar";

  return (
    <div>
      <MainLayout />
      {/* Tour Overlay will render portalled into the body when a tour is active */}
      <TourOverlay t={t} isRTL={isRTL} />
    </div>
  );
}

3. Start a Tour

Use the useTour hook in any component to trigger a tour by its ID.

import React from "react";
import { useTour } from "goguide";

export function HelpButton() {
  const { startTour } = useTour();

  return (
    <button onClick={() => startTour("dashboard-main", { force: true })}>
      Start Tour
    </button>
  );
}

Tour Configuration Schema

Each step in your configuration defines:

• selector: The CSS selector of the DOM element to highlight.
• titleKey: The translation key for the step's title.
• contentKey: The translation key for the step's description.
• placement: (Optional) Placement option (top | bottom | left | right | center).

Developer

Developed and maintained under the name of GoStack.