Feature Flagging for Free Trial Users on the Frontend

Feature flagging for free trial users is the practice of selectively enabling or disabling product features on the frontend based on a user's trial status, plan level, or usage limits. Unlike traditional feature flags used for gradual rollouts or A/B testing, trial-specific flags create a deliberate value gap between the trial experience and the paid product. When implemented correctly, feature gating during trials increases trial-to-paid conversion by 12-22% because users can see what they are missing and understand the concrete value of upgrading.

The challenge is implementation. You need a flag system that is simple enough to maintain, a UI that communicates the blocked state without frustrating users, and a measurement strategy to know which gated features actually drive upgrades. This guide covers all three, with production-ready code for each pattern. It also shows how TrialMoments handles the upgrade prompt UX when you call triggerBlockedFeature(), so you control the flags while TrialMoments handles the conversion moment.

The simplest feature flag system for trial gating is a configuration object that maps feature names to access rules. You do not need a third-party flag service to start. A static config, a React context provider, and a FeatureGate component give you everything you need for most trial gating scenarios.

The Feature Flag Config

// lib/feature-flags.ts

export type PlanLevel = 'trial' | 'starter' | 'pro' | 'enterprise';

export interface FeatureFlag {
  name: string;
  description: string;
  enabledForPlans: PlanLevel[];
  // Optional: limit usage instead of blocking entirely
  usageLimit?: {
    trial: number;
    starter: number;
    pro: number;
    enterprise: number;
  };
}

export const featureFlags: Record<string, FeatureFlag> = {
  'advanced-analytics': {
    name: 'Advanced Analytics',
    description: 'Custom dashboards, cohort analysis, and export',
    enabledForPlans: ['pro', 'enterprise'],
  },
  'team-collaboration': {
    name: 'Team Collaboration',
    description: 'Invite team members and share workspaces',
    enabledForPlans: ['starter', 'pro', 'enterprise'],
  },
  'api-access': {
    name: 'API Access',
    description: 'REST API with full read/write access',
    enabledForPlans: ['pro', 'enterprise'],
    usageLimit: {
      trial: 100,     // 100 API calls during trial
      starter: 10000,
      pro: 100000,
      enterprise: Infinity,
    },
  },
  'custom-branding': {
    name: 'Custom Branding',
    description: 'White-label with your brand colors and logo',
    enabledForPlans: ['enterprise'],
  },
  'export-csv': {
    name: 'CSV Export',
    description: 'Export data to CSV and Excel formats',
    enabledForPlans: ['starter', 'pro', 'enterprise'],
    usageLimit: {
      trial: 3,       // 3 exports during trial
      starter: 50,
      pro: Infinity,
      enterprise: Infinity,
    },
  },
};

This config-driven approach has a major advantage: product and engineering can update gating rules without deploying code. Move the config to a CMS, database, or environment variable and you have a lightweight feature flag system without any third-party dependency.

The Feature Flag Context Provider

// contexts/FeatureFlagContext.tsx
'use client';

import React, { createContext, useContext, useMemo } from 'react';
import { featureFlags, PlanLevel, FeatureFlag } from '@/lib/feature-flags';

interface FeatureFlagContextValue {
  userPlan: PlanLevel;
  isFeatureEnabled: (featureName: string) => boolean;
  getFeatureFlag: (featureName: string) => FeatureFlag | undefined;
  getRemainingUsage: (featureName: string, currentUsage: number) => number;
}

const FeatureFlagContext = createContext<FeatureFlagContextValue | null>(null);

export function FeatureFlagProvider({
  userPlan,
  children,
}: {
  userPlan: PlanLevel;
  children: React.ReactNode;
}) {
  const value = useMemo(() => ({
    userPlan,

    isFeatureEnabled: (featureName: string): boolean => {
      const flag = featureFlags[featureName];
      if (!flag) return true; // unknown features default to enabled
      return flag.enabledForPlans.includes(userPlan);
    },

    getFeatureFlag: (featureName: string) => featureFlags[featureName],

    getRemainingUsage: (featureName: string, currentUsage: number): number => {
      const flag = featureFlags[featureName];
      if (!flag?.usageLimit) return Infinity;
      const limit = flag.usageLimit[userPlan] ?? 0;
      return Math.max(0, limit - currentUsage);
    },
  }), [userPlan]);

  return (
    <FeatureFlagContext.Provider value={value}>
      {children}
    </FeatureFlagContext.Provider>
  );
}

export function useFeatureFlags() {
  const context = useContext(FeatureFlagContext);
  if (!context) {
    throw new Error('useFeatureFlags must be used within FeatureFlagProvider');
  }
  return context;
}

The FeatureGate Component

This is the component you wrap around any gated feature. It checks the flag, renders the feature if enabled, or renders a blocked-state fallback if not. The fallback is where conversion happens, so its design matters enormously. For more on trial feature gating patterns, see our dedicated guide.

// components/FeatureGate.tsx
'use client';

import React from 'react';
import { useFeatureFlags } from '@/contexts/FeatureFlagContext';

interface FeatureGateProps {
  featureName: string;
  children: React.ReactNode;
  fallback?: React.ReactNode;
  onBlocked?: () => void;
}

export function FeatureGate({
  featureName,
  children,
  fallback,
  onBlocked,
}: FeatureGateProps) {
  const { isFeatureEnabled, getFeatureFlag } = useFeatureFlags();

  if (isFeatureEnabled(featureName)) {
    return <>{children}</>;
  }

  const flag = getFeatureFlag(featureName);

  // Default fallback: a locked-feature card
  const defaultFallback = (
    <div className="relative rounded-lg border-2 border-dashed border-gray-300
                    bg-gray-50 p-8 text-center">
      <div className="mx-auto w-12 h-12 rounded-full bg-gray-200
                      flex items-center justify-center mb-4">
        <svg className="w-6 h-6 text-gray-400" fill="none" viewBox="0 0 24 24"
             stroke="currentColor">
          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2
                   0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
        </svg>
      </div>
      <h3 className="text-lg font-semibold mb-2">
        {flag?.name ?? 'Premium Feature'}
      </h3>
      <p className="text-sm text-gray-500 mb-4">
        {flag?.description ?? 'This feature is available on a paid plan.'}
      </p>
      <button
        onClick={onBlocked}
        className="px-6 py-2 bg-blue-600 text-white rounded-lg
                   font-semibold hover:bg-blue-700 transition-colors"
      >
        Upgrade to Unlock
      </button>
    </div>
  );

  return <>{fallback ?? defaultFallback}</>;
}

Usage in your app:

// In any component
import { FeatureGate } from '@/components/FeatureGate';

function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Basic reports: available to everyone */}
      <BasicReports />

      {/* Advanced analytics: gated for trial users */}
      <FeatureGate
        featureName="advanced-analytics"
        onBlocked={() => {
          // Track that user attempted to access this feature
          analytics.track('feature_blocked', { feature: 'advanced-analytics' });
        }}
      >
        <AdvancedAnalytics />
      </FeatureGate>
    </div>
  );
}

Beyond simple on/off gating, three advanced patterns significantly improve trial conversion: percentage rollout, plan-based progressive gating, and usage-based limits. Each pattern creates a different upgrade motivation.

// lib/percentage-rollout.ts

export function isInRollout(
  userId: string,
  featureName: string,
  percentage: number
): boolean {
  // Deterministic hash so the same user always gets the same result
  const hash = simpleHash(userId + featureName);
  return (hash % 100) < percentage;
}

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = ((hash << 5) - hash) + char;
    hash |= 0; // Convert to 32-bit integer
  }
  return Math.abs(hash);
}

// Usage: Give 30% of trial users access to advanced analytics
const hasAdvancedAnalytics = isInRollout(user.id, 'advanced-analytics', 30);

// lib/progressive-gating.ts

interface TrialPhase {
  startDay: number;
  endDay: number;
  enabledPlans: PlanLevel[];
}

const trialPhases: TrialPhase[] = [
  { startDay: 1, endDay: 3, enabledPlans: ['trial', 'starter'] },
  { startDay: 4, endDay: 7, enabledPlans: ['trial', 'starter', 'pro'] },
  { startDay: 8, endDay: 14, enabledPlans: ['trial', 'starter'] },
];

export function getTrialPlanLevel(trialStartDate: Date): PlanLevel[] {
  const daysSinceStart = Math.floor(
    (Date.now() - trialStartDate.getTime()) / (1000 * 60 * 60 * 24)
  );

  const phase = trialPhases.find(
    p => daysSinceStart >= p.startDay && daysSinceStart <= p.endDay
  );

  return phase?.enabledPlans ?? ['trial'];
}

// components/UsageLimitGate.tsx
'use client';

import { useFeatureFlags } from '@/contexts/FeatureFlagContext';

interface UsageLimitGateProps {
  featureName: string;
  currentUsage: number;
  children: React.ReactNode;
  onLimitReached: () => void;
}

export function UsageLimitGate({
  featureName,
  currentUsage,
  children,
  onLimitReached,
}: UsageLimitGateProps) {
  const { getRemainingUsage, getFeatureFlag } = useFeatureFlags();
  const remaining = getRemainingUsage(featureName, currentUsage);

  if (remaining <= 0) {
    const flag = getFeatureFlag(featureName);
    return (
      <div className="rounded-lg border border-amber-300 bg-amber-50 p-6">
        <p className="font-semibold text-amber-800 mb-2">
          You've used all {currentUsage} of your trial {flag?.name} quota
        </p>
        <p className="text-sm text-amber-700 mb-4">
          Upgrade to get unlimited access to {flag?.name?.toLowerCase()}.
        </p>
        <button onClick={onLimitReached}
                className="px-4 py-2 bg-amber-600 text-white rounded-lg
                           font-medium hover:bg-amber-700">
          Upgrade for Unlimited Access
        </button>
      </div>
    );
  }

  return (
    <>
      {remaining <= 2 && (
        <div className="text-sm text-amber-600 mb-2">
          {remaining} use{remaining !== 1 ? 's' : ''} remaining in your trial
        </div>
      )}
      {children}
    </>
  );
}

If you already use LaunchDarkly, Flagsmith, or another flag service, you do not need to build a separate system for trial gating. Instead, extend your existing flags with trial-specific targeting rules. The key is to pass user plan and trial status as context attributes so your flag rules can target trial users specifically.

LaunchDarkly Integration

// lib/launchdarkly-trial.ts
import { LDClient } from 'launchdarkly-js-client-sdk';

export function initTrialFlags(ldClient: LDClient, user: {
  id: string;
  plan: string;
  trialDaysRemaining: number;
  trialStartDate: string;
}) {
  // Set user context with trial attributes
  ldClient.identify({
    key: user.id,
    custom: {
      plan: user.plan,
      isTrialUser: user.plan === 'trial',
      trialDaysRemaining: user.trialDaysRemaining,
      trialStartDate: user.trialStartDate,
    },
  });
}

// In LaunchDarkly dashboard, create targeting rules:
// IF plan = "trial" AND trialDaysRemaining <= 3
//   THEN enable "show-urgency-banner" = true
//
// IF plan = "trial"
//   THEN enable "advanced-analytics" = false
//   ELSE enable "advanced-analytics" = true

Flagsmith Integration

// lib/flagsmith-trial.ts
import flagsmith from 'flagsmith';

export async function initTrialFlags(user: {
  id: string;
  plan: string;
  trialDaysRemaining: number;
}) {
  await flagsmith.identify(user.id, {
    plan: user.plan,
    is_trial: user.plan === 'trial',
    trial_days_remaining: user.trialDaysRemaining,
  });
}

// Check flags with Flagsmith
export function isFeatureEnabled(featureName: string): boolean {
  return flagsmith.hasFeature(featureName);
}

export function getFeatureValue(featureName: string): string | number | boolean {
  return flagsmith.getValue(featureName);
}

The blocked-state UX is the single most important design decision in trial feature flagging. It is the moment where a user discovers a feature they cannot access and decides whether to upgrade or leave. Most products get this wrong by either hiding gated features (users never see the value) or showing a generic "upgrade" message (no context, no motivation). The best paywall design patterns follow three principles.

Here is a more conversion-focused FeatureGate fallback that applies these principles:

// components/PremiumFeatureBlock.tsx

interface PremiumFeatureBlockProps {
  featureName: string;
  title: string;
  description: string;
  previewImageUrl?: string;
  upgradeUrl: string;
  onUpgradeClick?: () => void;
}

export function PremiumFeatureBlock({
  featureName,
  title,
  description,
  previewImageUrl,
  upgradeUrl,
  onUpgradeClick,
}: PremiumFeatureBlockProps) {
  return (
    <div className="relative rounded-xl border-2 border-dashed border-gray-200
                    overflow-hidden">
      {/* Blurred preview background */}
      {previewImageUrl && (
        <div className="absolute inset-0 blur-sm opacity-30">
          <img src={previewImageUrl} alt="" className="w-full h-full
               object-cover" />
        </div>
      )}

      {/* Overlay content */}
      <div className="relative bg-white/80 backdrop-blur-sm p-8 text-center">
        <div className="inline-flex items-center gap-2 px-3 py-1 rounded-full
                        bg-primary/10 text-primary text-sm font-medium mb-4">
          <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24"
               stroke="currentColor">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                  d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2
                     0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
          </svg>
          Pro Feature
        </div>
        <h3 className="text-xl font-bold mb-2">{title}</h3>
        <p className="text-gray-600 mb-6 max-w-md mx-auto">{description}</p>
        <a
          href={upgradeUrl}
          onClick={onUpgradeClick}
          className="inline-flex items-center gap-2 px-6 py-3 bg-primary
                     text-white rounded-lg font-semibold hover:bg-primary/90
                     transition-colors"
        >
          Upgrade to Unlock
          <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24"
               stroke="currentColor">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                  d="M13 7l5 5m0 0l-5 5m5-5H6" />
          </svg>
        </a>
      </div>
    </div>
  );
}

Feature flags without measurement are guesswork. You need to track three events for each gated feature to understand its impact on trial conversion rates.

analytics.track('feature_encountered', {
  feature: featureName,
  userPlan: 'trial',
  trialDay: getDaysSinceTrialStart(),
});

analytics.track('upgrade_intent', {
  feature: featureName,
  source: 'feature_gate',
  trialDay: getDaysSinceTrialStart(),
});

TrialMoments does not replace your feature flagging logic. It complements it. You decide which features are gated and implement the flag checks using any of the patterns above. When a user hits a gate, you call triggerBlockedFeature() and TrialMoments displays a conversion-optimized modal with the feature value prop, remaining trial context, and a clear upgrade path.

// Initialize TrialMoments once
TrialMoments.init({
  accountId: 'your-id',
  trialEndDate: '2026-04-15',
  upgradeUrl: '/upgrade',
});

// In your FeatureGate onBlocked callback:
<FeatureGate
  featureName="advanced-analytics"
  onBlocked={() => {
    // TrialMoments shows a conversion-optimized upgrade prompt
    TrialMoments.triggerBlockedFeature('advanced-analytics');
  }}
>
  <AdvancedAnalytics />
</FeatureGate>

FAQ: Feature Flagging for Trial Users