@guidelytech/react

React provider and hooks for Guidely. Wraps @guidelytech/sdk-core; works with React 18/19, SSR and Strict Mode.

pnpm add @guidelytech/react

import { GuidelyProvider, useGuidely } from "@guidelytech/react";

export function App({ children }) {
  return (
    <GuidelyProvider projectId="pk_dev_…" apiUrl="http://localhost:3000" user={{ id: "u1", traits: { role: "admin" } }}>
      {children}
    </GuidelyProvider>
  );
}

function HelpMenu() {
  const guidely = useGuidely();
  return <button onClick={() => guidely.startGuide("new-user-onboarding")}>Restart tour</button>;
}

| Export | Description | |---|---| | GuidelyProvider | Accepts every GuidelyOptions field plus user?: { id, traits?, account? } and children. Creates the client inside an effect (never during SSR), destroys it on unmount; Strict Mode's double invoke yields exactly one live client. Changing projectId/environment/apiUrl recreates the client; changing user re-identifies (undefined resets). | | useGuidely() | The client, or a no-op proxy on the server / before mount (methods return false, [], null or resolved promises). | | useGuidelyReady() | true once config is loaded. | | useGuidelyIdentify(userId, traits?, account?) | Effect helper that identifies when the arguments change. | | useGuidelyEvent(event, handler) | Subscribes for the component lifetime (latest handler is used). | | useChecklistProgress(idOrKey) | Live { completedTaskIds, completedAt, dismissedAt }. | | useGuideState(idOrKey) | Live { active, completed, stepId, stepIndex, guide }. | | noopClient | The no-op client instance (flag getters return their fallbacks). | | useFlag(key, fallback = false) | Is the boolean flag on? | | useFeatureValue(key, fallback) | A flag's value (string, number, JSON); fallback when missing or of another type. | | useFlagDetails(key, fallback) | Value plus reason, ruleId, variationId, experiment. | | useFlags() / useFlagsReady() / useFlagsClient() | Every flag's value / loaded yet / the flags client (null on the server). | | <Feature flag="x" fallback={…}> (alias <FeatureFlag>) | Renders children when the flag is on, else fallback. | | <FeatureValue flag="x" value="green" fallback={…}> | Renders children when the flag's value equals value. | | <FlagsProvider sdkKey="pk_…" attributes={…} payload={…}> | Flags only, without guides or analytics (accepts every flags client option). |

Feature flags

import { Feature, useFeatureValue, useFlag } from "@guidelytech/react";

function Checkout() {
  const newCheckout = useFlag("new-checkout");
  const color = useFeatureValue("checkout-button-color", "blue");
  return (
    <Feature flag="new-dashboard-banner" fallback={<OldBanner />}>
      <NewBanner />
    </Feature>
  );
}

The hooks read the GuidelyProvider's client (client.flags, same public key, identity/page/device attributes maintained for you) or a <FlagsProvider>. They subscribe with useSyncExternalStore and re-render only when a value changes. Before the client exists (server rendering, hydration) they read the bootstrap payload — <GuidelyProvider flagsPayload={…} flagAttributes={…}> or <FlagsProvider payload={…}> — evaluated with flagAttributes plus the user prop (id, traits, account), so server HTML and hydration match; without a payload they return fallbacks. GuidelyProvider also accepts flags={false} to turn flags off or flags={{ … }} for client options.

Types re-exported: GuidelyClient, GuidelyOptions, GuidelyEvents, GuidelyUser, ChecklistProgressState, PublishedGuide, GuideState, GuidelyProviderProps, and from @guidelytech/flags: FlagsClient, FlagsClientOptions, FlagDetails, FlagsBootstrap, FlagsPayload, Attributes, JsonValue, EvaluationResult.