Components Reference

This page provides a complete reference for all feature flag components available in the Next.js SDK.

Server Components

These components are async and designed for Server Components in the App Router.

Feature

Conditionally renders content when a feature is enabled. Set negate to render when it is off — the same attribute as .NET <feature negate>.

import { Feature } from '@ops-ai/nextjs-toggly-server'

// Show when enabled
<Feature featureKey="my-feature">
  <EnabledContent />
</Feature>

// Show when disabled
<Feature featureKey="my-feature" negate>
  <DisabledContent />
</Feature>

// Entity gate
<Feature featureKey="OrderBadge" context={order} contextKind="Order">
  <Badge />
</Feature>

// Multiple features (all must be enabled)
<Feature featureKey={['feature-a', 'feature-b']} requirement="all">
  <Content />
</Feature>

// Any feature enabled
<Feature featureKey={['feature-a', 'feature-b']} requirement="any">
  <Content />
</Feature>

Props:

Prop	Type	Default	Description
featureKey	string | string[]	required	Feature key(s) to check
requirement	'all' | 'any'	'all'	How to evaluate multiple features
negate	boolean	false	Render children when the feature is off
identity	string	—	User identity for this check only
context	object	—	Entity / page object for Context Property filters
contextKind	string	—	Catalog kind when context is a domain object
children	ReactNode	required	Content to render when the gate passes

FeatureVariant

Dual-slot helper for on vs off content in one call. Prefer two <Feature> / <Feature negate> blocks when you want the same off-path pattern as .NET.

import { FeatureVariant } from '@ops-ai/nextjs-toggly-server'

<FeatureVariant
  featureKey="checkout-flow"
  enabled={<NewPricing />}
  disabled={<LegacyPricing />}
/>

Props:

Prop	Type	Default	Description
featureKey	string	required	Feature key to check
identity	string	—	User identity for this check only
context / contextKind	entity	—	Same as Feature
enabled	ReactNode	required	Content when the feature is on
disabled	ReactNode	required	Content when the feature is off

---

Client Components

These components are designed for Client Components and include loading states.

Feature (Client)

'use client'
import { Feature } from '@ops-ai/nextjs-toggly-client'

// Show when enabled
<Feature featureKey="new-feature" loading={<LoadingSpinner />}>
  <NewFeature />
</Feature>

// Show when disabled
<Feature featureKey="new-feature" negate loading={<LoadingSpinner />}>
  <OldFeature />
</Feature>

Props:

Prop	Type	Default	Description
featureKey	string	required	Feature key to check
requirement	'all' | 'any'	'all'	How to evaluate multiple features
negate	boolean	false	Render children when the feature is off
loading	ReactNode	null	Content while loading
children	ReactNode	required	Content when the gate passes

FeatureGate

Evaluates multiple features with AND/OR logic. Set negate to render when the gate fails.

'use client'
import { FeatureGate } from '@ops-ai/nextjs-toggly-client'

<FeatureGate
  featureKeys={['premium', 'beta-tester']}
  requirement="all"
>
  <PremiumContent />
</FeatureGate>

<FeatureGate
  featureKeys={['premium', 'beta-tester']}
  requirement="all"
  negate
>
  <UpgradePrompt />
</FeatureGate>

Props:

Prop	Type	Default	Description
featureKeys	string[]	required	Feature keys to check
requirement	'all' | 'any'	'all'	Evaluation mode
negate	boolean	false	Render children when the gate fails
loading	ReactNode	null	Content while loading
children	ReactNode	required	Content when the gate passes

FeatureSwitch

Renders the first matching feature case.

'use client'
import { FeatureSwitch } from '@ops-ai/nextjs-toggly-client'

<FeatureSwitch
  cases={[
    { featureKey: 'checkout-v3', element: <CheckoutV3 /> },
    { featureKey: 'checkout-v2', element: <CheckoutV2 /> },
  ]}
  fallback={<CheckoutV1 />}
  loading={<CheckoutSkeleton />}
/>

Props:

Prop	Type	Default	Description
cases	FeatureSwitchCase[]	required	Feature cases to check
fallback	ReactNode	null	Default content
loading	ReactNode	null	Content while loading

FeatureSwitchCase:

interface FeatureSwitchCase {
  featureKey: string
  element: ReactNode
}

FeatureVariant (Client)

Dual-slot helper — prefer <Feature> / <Feature negate> for the primary off path.

'use client'
import { FeatureVariant } from '@ops-ai/nextjs-toggly-client'

<FeatureVariant
  featureKey="checkout-flow"
  enabled={<DashboardV2 />}
  disabled={<DashboardV1 />}
  loading={<DashboardSkeleton />}
/>

---

Patterns

Server + Client Hybrid

Use Server Components for initial render, Client for interactivity:

app/dashboard/page.tsx

import { Feature as ServerFeature } from '@ops-ai/nextjs-toggly-server'
import { DashboardClient } from './dashboard-client'

export default async function DashboardPage() {
  return (
    <ServerFeature featureKey="new-dashboard">
      {/* Server-rendered shell */}
      <DashboardShell>
        {/* Client component for interactivity */}
        <DashboardClient />
      </DashboardShell>
    </ServerFeature>
  )
}

app/dashboard/dashboard-client.tsx

'use client'
import { Feature } from '@ops-ai/nextjs-toggly-client'

export function DashboardClient() {
  return (
    <>
      <Feature featureKey="interactive-charts">
        <InteractiveCharts />
      </Feature>
      <Feature featureKey="interactive-charts" negate>
        <StaticCharts />
      </Feature>
    </>
  )
}

Nested Feature Gates

<Feature featureKey="premium-tier">
  <PremiumLayout>
    <Feature featureKey="analytics">
      <AnalyticsPanel />
    </Feature>

    <Feature featureKey="reports">
      <ReportsPanel />
    </Feature>

    <FeatureGate
      featureKeys={['ai-insights', 'beta-tester']}
      requirement="all"
    >
      <AIInsightsPanel />
    </FeatureGate>
  </PremiumLayout>
</Feature>

A/B Testing

<FeatureSwitch
  cases={[
    { featureKey: 'checkout-variant-a', element: <CheckoutA /> },
    { featureKey: 'checkout-variant-b', element: <CheckoutB /> },
    { featureKey: 'checkout-variant-c', element: <CheckoutC /> },
  ]}
  fallback={<CheckoutControl />}
/>

Gradual Rollout

<Feature featureKey="new-feature-10-percent">
  <NewFeature />
</Feature>
<Feature featureKey="new-feature-10-percent" negate>
  <CurrentFeature />
</Feature>

Maintenance Mode

<Feature featureKey="maintenance-complete" negate>
  <MaintenanceBanner>
    We're currently performing maintenance. Please check back later.
  </MaintenanceBanner>
</Feature>
<Feature featureKey="maintenance-complete">
  <NormalSiteContent />
</Feature>