Skip to main content

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

useFeatureFlag

A hook that checks a single feature flag through the analytics provider, with automatic polling for real-time flag updates.

Source file: template/hooks/use-feature-flag.ts

Overview​

useFeatureFlag provides a simple way to check whether a specific feature flag is enabled via the analytics provider (e.g., PostHog). It initializes with a default value, checks the flag immediately on mount, and then polls every 30 seconds for updates. This makes it suitable for feature flags that may change at runtime without requiring a page reload.

Unlike useFeatureFlags (which fetches server-side flags via an API endpoint), this hook communicates directly with the analytics SDK's feature flag system.

Signature​

function useFeatureFlag(flagKey: string, defaultValue?: boolean): boolean

Parameters​

ParameterTypeDefaultDescription
flagKeystring--The feature flag key to check (must match the key in your analytics provider)
defaultValuebooleanfalseThe value to use before the flag is resolved and as the initial state

Return Value​

boolean -- true if the feature flag is enabled, false otherwise. Returns defaultValue until the first check completes.

Implementation Details​

Lifecycle​

  1. Initial state: The hook initializes isEnabled state to defaultValue.
  2. Immediate check: On mount (and when flagKey or defaultValue changes), the flag is checked via analytics.isFeatureEnabled(flagKey, defaultValue).
  3. Polling: A setInterval runs every 30 seconds to re-check the flag value, allowing the UI to react to flag changes without a page reload.
  4. Cleanup: The interval is cleared when the component unmounts or when dependencies change.

Analytics Integration​

The hook delegates to analytics.isFeatureEnabled() from @/lib/analytics. This function is expected to return a boolean indicating whether the flag is enabled. The analytics module must be initialized with a provider that supports feature flags (such as PostHog).

Polling Interval​

The polling interval is hardcoded at 30 seconds (30,000 ms). This provides a reasonable balance between responsiveness and API load.

Usage Examples​

Basic feature gating​

import { useFeatureFlag } from '@/hooks/use-feature-flag';

function NewFeatureBanner() {
  const showBanner = useFeatureFlag('new-feature-banner', false);

  if (!showBanner) return null;

  return (
    <div className="bg-blue-100 p-4 rounded">
      Try our new feature!
    </div>
  );
}

A/B testing a component variant​

import { useFeatureFlag } from '@/hooks/use-feature-flag';

function SearchBar() {
  const useNewSearch = useFeatureFlag('enhanced-search', false);

  return useNewSearch
    ? <EnhancedSearchBar />
    : <BasicSearchBar />;
}

With default enabled​

// Feature defaults to enabled, can be remotely disabled
const maintenanceMode = useFeatureFlag('maintenance-mode', false);
const betaFeatures = useFeatureFlag('beta-features', true);

Conditional data loading​

function AnalyticsDashboard() {
  const showAdvancedMetrics = useFeatureFlag('advanced-metrics', false);

  const { data } = useQuery({
    queryKey: ['metrics', showAdvancedMetrics],
    queryFn: () => fetchMetrics({ advanced: showAdvancedMetrics }),
  });

  return (
    <div>
      <BasicMetrics data={data} />
      {showAdvancedMetrics && <AdvancedMetrics data={data} />}
    </div>
  );
}

Requirements​

DependencyPurpose
@/lib/analyticsProvides the analytics.isFeatureEnabled() method for flag evaluation

Comparison with useFeatureFlags​

AspectuseFeatureFlaguseFeatureFlags
SourceAnalytics provider (e.g., PostHog)Server API endpoint
ScopeSingle flagAll flags at once
CachingLocal state with pollingTanStack Query cache
Update mechanism30-second polling intervalCache-based with stale time
Best forAnalytics-driven feature flagsServer-configured feature toggles