@posthog/react 1.9.1 → 1.10.1

package/src/hooks/__tests__/featureFlags.test.tsx

@@ -115,6 +115,67 @@ describe('feature flag hooks', () => {
         expect(result.current).toEqual(expected)
     })
 
+    describe('useFeatureFlagEnabled defaultValue', () => {
+        // A client whose flags have loaded but where isFeatureEnabled returns undefined,
+        // i.e. the flag is absent from the payload. The default beforeEach mock coerces
+        // every result with `!!`, so it can never produce the undefined we need here.
+        function renderWithUnknownFlag() {
+            const client = {
+                isFeatureEnabled: () => undefined,
+                onFeatureFlags: () => () => {},
+                featureFlags: {
+                    hasLoadedFlags: true,
+                } as unknown as PostHog['featureFlags'],
+            } as unknown as PostHog
+
+            // eslint-disable-next-line react/display-name
+            return ({ children }: { children: React.ReactNode }) => (
+                <PostHogProvider client={client}>{children}</PostHogProvider>
+            )
+        }
+
+        it.each([
+            [false as boolean | undefined, false],
+            [true as boolean | undefined, true],
+            [undefined, undefined],
+        ])('returns %s for an unknown flag when defaultValue is %s', (defaultValue, expected) => {
+            const { result } = renderHook(() => useFeatureFlagEnabled('missing', defaultValue as boolean), {
+                wrapper: renderWithUnknownFlag(),
+            })
+            expect(result.current).toBe(expected)
+        })
+
+        it('prefers the real flag value over the default', () => {
+            const { result } = renderHook(() => useFeatureFlagEnabled('example_feature_false', true), {
+                wrapper: renderProvider,
+            })
+            expect(result.current).toBe(false)
+        })
+
+        it('applies the default in the bootstrap branch when the flag is absent', () => {
+            const client = {
+                isFeatureEnabled: () => undefined,
+                onFeatureFlags: () => () => {},
+                config: {
+                    bootstrap: {
+                        featureFlags: { other_flag: true },
+                    },
+                },
+                featureFlags: {
+                    hasLoadedFlags: false,
+                } as unknown as PostHog['featureFlags'],
+            } as unknown as PostHog
+
+            // eslint-disable-next-line react/display-name
+            const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+                <PostHogProvider client={client}>{children}</PostHogProvider>
+            )
+
+            const { result } = renderHook(() => useFeatureFlagEnabled('my_flag', false), { wrapper })
+            expect(result.current).toBe(false)
+        })
+    })
+
     describe('useFeatureFlagResult', () => {
         describe('bootstrap fallback', () => {
             function renderWithBootstrap(

package/src/hooks/useFeatureFlagEnabled.ts

@@ -2,7 +2,25 @@ import { useContext, useEffect, useState } from 'react'
 import { PostHogContext } from '../context'
 import { isUndefined } from '../utils/type-utils'
 
-export function useFeatureFlagEnabled(flag: string): boolean | undefined {
+/**
+ * Check whether a feature flag is enabled for the current user.
+ *
+ * Returns `undefined` while flags are still loading or when the flag is absent, so callers can
+ * distinguish "not known yet" from "disabled".
+ *
+ * @param flag Key of the feature flag.
+ * @returns Whether the flag is enabled, or `undefined` if not yet loaded or not found.
+ */
+export function useFeatureFlagEnabled(flag: string): boolean | undefined
+/**
+ * Check whether a feature flag is enabled for the current user.
+ *
+ * @param flag Key of the feature flag.
+ * @param defaultValue Returned instead of `undefined` while flags are loading or when the flag is absent.
+ * @returns Whether the flag is enabled, falling back to `defaultValue` when the value is unknown.
+ */
+export function useFeatureFlagEnabled(flag: string, defaultValue: boolean): boolean
+export function useFeatureFlagEnabled(flag: string, defaultValue?: boolean): boolean | undefined {
     const { client, bootstrap } = useContext(PostHogContext)
 
     const [featureEnabled, setFeatureEnabled] = useState<boolean | undefined>(() => client.isFeatureEnabled(flag))
@@ -17,8 +35,9 @@ export function useFeatureFlagEnabled(flag: string): boolean | undefined {
 
     // if the client is not loaded yet, check if we have a bootstrapped value and then true/false it
     if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlags) {
-        return isUndefined(bootstrapped) ? undefined : !!bootstrapped
+        return isUndefined(bootstrapped) ? defaultValue : !!bootstrapped
     }
 
-    return featureEnabled
+    // while the flag value is unknown (flags not loaded, or the flag is absent), fall back to defaultValue
+    return isUndefined(featureEnabled) ? defaultValue : featureEnabled
 }