feat(react): add FeatureFlag component

packages/react/README.md

@@ -50,6 +50,7 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc
   - [Usage](#usage)
     - [OpenFeatureProvider context provider](#openfeatureprovider-context-provider)
     - [Evaluation hooks](#evaluation-hooks)
+    - [Declarative components](#declarative-components)
     - [Multiple Providers and Domains](#multiple-providers-and-domains)
     - [Re-rendering with Context Changes](#re-rendering-with-context-changes)
     - [Re-rendering with Flag Configuration Changes](#re-rendering-with-flag-configuration-changes)
@@ -170,6 +171,72 @@ const {
 } = useBooleanFlagDetails('new-message', false);
 ```
 
+#### Declarative components
+
+The React SDK includes declarative components for feature flagging that provide a more JSX-native approach to conditional rendering.
+
+##### FeatureFlag Component
+
+The `FeatureFlag` component conditionally renders its children based on feature flag evaluation:
+
+```tsx
+import { FeatureFlag } from '@openfeature/react-sdk';
+
+function App() {
+  return (
+    <OpenFeatureProvider>
+      {/* Basic usage - renders children when flag is truthy */}
+      <FeatureFlag flagKey="new-feature" defaultValue={false}>
+        <NewFeatureComponent />
+      </FeatureFlag>
+
+      {/* Match specific values */}
+      <FeatureFlag flagKey="theme" match="dark" defaultValue="light">
+        <DarkThemeStyles />
+      </FeatureFlag>
+
+      {/* Boolean flag with fallback */}
+      <FeatureFlag 
+        flagKey="premium-feature" 
+        match={true} 
+        defaultValue={false}
+        fallback={<UpgradePrompt />}
+      >
+        <PremiumContent />
+      </FeatureFlag>
+
+      {/* Custom predicate function for complex matching */}
+      <FeatureFlag
+        flagKey="user-segment"
+        defaultValue=""
+        predicate={(expected, actual) => actual.value.includes('beta')}
+      >
+        <BetaFeatures />
+      </FeatureFlag>
+
+      {/* Function as children for accessing flag details */}
+      <FeatureFlag flagKey="experiment" defaultValue="control">
+        {(flagDetails) => (
+          <ExperimentComponent 
+            variant={flagDetails.value} 
+            reason={flagDetails.details.reason}
+          />
+        )}
+      </FeatureFlag>
+    </OpenFeatureProvider>
+  );
+}
+```
+
+The `FeatureFlag` component supports the following props:
+
+- **`flagKey`** (required): The feature flag key to evaluate
+- **`defaultValue`** (required): Default value when the flag is not available
+- **`match`** (optional): Value to match against the flag value. By default, strict equality (===) is used for comparison
+- **`predicate`** (optional): Custom function for matching logic that receives the expected value and evaluation details
+- **`children`**: Content to render when condition is met (can be JSX or a function receiving flag details)
+- **`fallback`** (optional): Content to render when condition is not met
+
 #### Multiple Providers and Domains
 
 Multiple providers can be used by passing a `domain` to the `OpenFeatureProvider`:
@@ -306,8 +373,8 @@ function MyComponent() {
 ### Testing
 
 The React SDK includes a built-in context provider for testing.
-This allows you to easily test components that use evaluation hooks, such as `useFlag`.
-If you try to test a component (in this case, `MyComponent`) which uses an evaluation hook, you might see an error message like:
+This allows you to easily test components that use evaluation hooks (such as `useFlag`) or declarative components (such as `FeatureFlag`).
+If you try to test a component (in this case, `MyComponent`) which uses feature flags, you might see an error message like:
 
 > No OpenFeature client available - components using OpenFeature must be wrapped with an `<OpenFeatureProvider>`.
 
@@ -328,6 +395,16 @@ If you'd like to control the values returned by the evaluation hooks, you can pa
 <OpenFeatureTestProvider flagValueMap={{ 'my-boolean-flag': true }}>
   <MyComponent />
 </OpenFeatureTestProvider>
+
+// testing declarative FeatureFlag components
+<OpenFeatureTestProvider flagValueMap={{ 'new-feature': true, 'theme': 'dark' }}>
+  <FeatureFlag flagKey="new-feature" defaultValue={false}>
+    <NewFeature />
+  </FeatureFlag>
+  <FeatureFlag flagKey="theme" match="dark" defaultValue="light">
+    <DarkMode />
+  </FeatureFlag>
+</OpenFeatureTestProvider>
 ```
 
 Additionally, you can pass an artificial delay for the provider startup to test your suspense boundaries or loaders/spinners impacted by feature flags:

packages/react/src/declarative/FeatureFlag.tsx

@@ -0,0 +1,104 @@
+import React from 'react';
+import { useFlag } from '../evaluation';
+import type { FlagQuery } from '../query';
+import type { FlagValue, EvaluationDetails } from '@openfeature/core';
+
+/**
+ * Default predicate function that checks if the expected value equals the actual flag value.
+ * @param {T} expected The expected value to match against
+ * @param {EvaluationDetails<T>} actual The evaluation details containing the actual flag value
+ * @returns {boolean} true if the values match, false otherwise
+ */
+function equals<T extends FlagValue>(expected: T, actual: EvaluationDetails<T>): boolean {
+  return expected === actual.value;
+}
+
+/**
+ * Props for the FeatureFlag component that conditionally renders content based on feature flag state.
+ * @interface FeatureFlagProps
+ */
+interface FeatureFlagProps<T extends FlagValue = FlagValue> {
+  /**
+   * The key of the feature flag to evaluate.
+   */
+  flagKey: string;
+
+  /**
+   * Optional value to match against the feature flag value.
+   * If provided, the component will only render children when the flag value matches this value.
+   * By default, strict equality (===) is used for comparison.
+   * If a boolean, it will check if the flag is enabled (true) or disabled (false).
+   * If a string, it will check if the flag variant equals this string.
+   */
+  match?: T;
+
+  /**
+   * Optional predicate function for custom matching logic.
+   * If provided, this function will be used instead of the default equality check.
+   * @param expected The expected value (from match prop)
+   * @param actual The evaluation details
+   * @returns true if the condition is met, false otherwise
+   */
+  predicate?: (expected: T | undefined, actual: EvaluationDetails<T>) => boolean;
+
+  /**
+   * Default value to use when the feature flag is not found.
+   */
+  defaultValue: T;
+
+  /**
+   * Content to render when the feature flag condition is met.
+   * Can be a React node or a function that receives flag query details and returns a React node.
+   */
+  children: React.ReactNode | ((details: FlagQuery<T>) => React.ReactNode);
+
+  /**
+   * Optional content to render when the feature flag condition is not met.
+   * Can be a React node or a function that receives evaluation details and returns a React node.
+   */
+  fallback?: React.ReactNode | ((details: EvaluationDetails<T>) => React.ReactNode);
+}
+
+/**
+ * FeatureFlag component that conditionally renders its children based on the evaluation of a feature flag.
+ * @param {FeatureFlagProps} props The properties for the FeatureFlag component.
+ * @returns {React.ReactElement | null} The rendered component or null if the feature is not enabled.
+ */
+export function FeatureFlag<T extends FlagValue = FlagValue>({
+  flagKey,
+  match,
+  predicate,
+  defaultValue,
+  children,
+  fallback = null,
+}: FeatureFlagProps<T>): React.ReactElement | null {
+  const details = useFlag(flagKey, defaultValue, {
+    updateOnContextChanged: true,
+  });
+
+  // If the flag evaluation failed, we render the fallback
+  if (details.reason === 'ERROR') {
+    const fallbackNode: React.ReactNode = typeof fallback === 'function' ? fallback(details.details as EvaluationDetails<T>) : fallback;
+    return <>{fallbackNode}</>;
+  }
+
+  // Use custom predicate if provided, otherwise use default matching logic
+  let shouldRender = false;
+  if (predicate) {
+    shouldRender = predicate(match, details.details as EvaluationDetails<T>);
+  } else if (match !== undefined) {
+    // Default behavior: check if match value equals flag value
+    shouldRender = equals(match, details.details as EvaluationDetails<T>);
+  } else {
+    // If no match value is provided, render if flag is truthy
+    shouldRender = Boolean(details.value);
+  }
+
+  if (shouldRender) {
+    const childNode: React.ReactNode = typeof children === 'function' ? children(details as FlagQuery<T>) : children;
+    return <>{childNode}</>;
+  }
+
+  const fallbackNode: React.ReactNode = typeof fallback === 'function' ? fallback(details.details as EvaluationDetails<T>) : fallback;
+  return <>{fallbackNode}</>;
+}

packages/react/src/declarative/index.ts

@@ -0,0 +1 @@
+export * from './FeatureFlag';

packages/react/src/index.ts

@@ -1,3 +1,4 @@
+export * from './declarative';
 export * from './evaluation';
 export * from './query';
 export * from './provider';