diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml
index e0ceaa0d..be37e1d8 100644
--- a/.github/workflows/node.js.yml
+++ b/.github/workflows/node.js.yml
@@ -88,6 +88,29 @@ jobs:
       - name: Setup iOS
         working-directory: ./Samples/SimpleMixpanel/ios
         run: pod install --repo-update
+      - name: List available simulators
+        run: xcrun simctl list devices available
+      - name: Boot iOS Simulator
+        run: |
+          # Get list of available iPhone simulators
+          # Note: jq is pre-installed on macOS GitHub Actions runners
+          SIMULATOR_ID=$(xcrun simctl list devices available -j | jq -r '.devices | to_entries[] | .value[] | select(.name | contains("iPhone")) | .udid' | head -n 1)
+          if [ -z "$SIMULATOR_ID" ]; then
+            echo "Error: No iPhone simulator found"
+            exit 1
+          fi
+          echo "Found simulator: $SIMULATOR_ID"
+          # Check if simulator is already booted
+          DEVICE_LIST=$(xcrun simctl list devices)
+          if echo "$DEVICE_LIST" | grep -q "$SIMULATOR_ID.*Booted"; then
+            echo "Simulator already booted"
+          else
+            echo "Booting simulator..."
+            xcrun simctl boot "$SIMULATOR_ID"
+          fi
+          # Verify simulator is booted
+          echo "Booted simulators:"
+          xcrun simctl list devices | grep Booted
       - name: Test iOS
         working-directory: ./Samples/SimpleMixpanel
         run: react-native run-ios
diff --git a/MixpanelReactNative.podspec b/MixpanelReactNative.podspec
index a716caaf..97b7aef4 100644
--- a/MixpanelReactNative.podspec
+++ b/MixpanelReactNative.podspec
@@ -19,5 +19,5 @@ Pod::Spec.new do |s|
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
 
   s.dependency "React-Core"
-  s.dependency "Mixpanel-swift", '5.1.0'
+  s.dependency "Mixpanel-swift", '5.1.3'
 end
diff --git a/__tests__/flags.test.js b/__tests__/flags.test.js
new file mode 100644
index 00000000..302d927a
--- /dev/null
+++ b/__tests__/flags.test.js
@@ -0,0 +1,612 @@
+import { Mixpanel } from "mixpanel-react-native";
+import { NativeModules } from "react-native";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+const mockNativeModule = NativeModules.MixpanelReactNative;
+
+// Mock fetch for JavaScript mode
+global.fetch = jest.fn();
+
+describe("Feature Flags", () => {
+  const testToken = "test-token-123";
+  let mixpanel;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    AsyncStorage.clear();
+    if (global.fetch.mockClear) {
+      global.fetch.mockClear();
+    }
+  });
+
+  describe("Flags Property Access", () => {
+    it("should expose flags property on Mixpanel instance", async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+
+      expect(mixpanel.flags).toBeDefined();
+    });
+
+    it("should lazy-load flags property", async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+
+      const flags1 = mixpanel.flags;
+      const flags2 = mixpanel.flags;
+
+      expect(flags1).toBe(flags2); // Should be same instance
+    });
+
+    it("should initialize flags when enabled in init options", async () => {
+      mockNativeModule.areFlagsReadySync.mockReturnValue(false);
+      mockNativeModule.loadFlags.mockResolvedValue(true);
+
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init(false, {}, "https://api.mixpanel.com", false, {
+        enabled: true,
+      });
+
+      expect(mockNativeModule.loadFlags).toHaveBeenCalledWith(testToken);
+    });
+  });
+
+  describe("Native Mode - Synchronous Methods", () => {
+    beforeEach(async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+    });
+
+    describe("areFlagsReady", () => {
+      it("should return false when flags are not ready", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(false);
+
+        const ready = mixpanel.flags.areFlagsReady();
+
+        expect(ready).toBe(false);
+        expect(mockNativeModule.areFlagsReadySync).toHaveBeenCalledWith(
+          testToken
+        );
+      });
+
+      it("should return true when flags are ready", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+
+        const ready = mixpanel.flags.areFlagsReady();
+
+        expect(ready).toBe(true);
+      });
+    });
+
+    describe("getVariantSync", () => {
+      const fallbackVariant = { key: "fallback", value: "default" };
+
+      it("should return fallback when flags not ready", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(false);
+
+        const variant = mixpanel.flags.getVariantSync("test-flag", fallbackVariant);
+
+        expect(variant).toEqual(fallbackVariant);
+        expect(mockNativeModule.getVariantSync).not.toHaveBeenCalled();
+      });
+
+      it("should get variant when flags are ready", () => {
+        const expectedVariant = { key: "treatment", value: "blue", experimentID: "exp123" };
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantSync.mockReturnValue(expectedVariant);
+
+        const variant = mixpanel.flags.getVariantSync("test-flag", fallbackVariant);
+
+        expect(variant).toEqual(expectedVariant);
+        expect(mockNativeModule.getVariantSync).toHaveBeenCalledWith(
+          testToken,
+          "test-flag",
+          fallbackVariant
+        );
+      });
+
+      it("should handle null feature name", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantSync.mockReturnValue(fallbackVariant);
+
+        const variant = mixpanel.flags.getVariantSync(null, fallbackVariant);
+
+        expect(variant).toEqual(fallbackVariant);
+      });
+    });
+
+    describe("getVariantValueSync", () => {
+      it("should return fallback when flags not ready", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(false);
+
+        const value = mixpanel.flags.getVariantValueSync("test-flag", "default");
+
+        expect(value).toBe("default");
+        expect(mockNativeModule.getVariantValueSync).not.toHaveBeenCalled();
+      });
+
+      it("should get value when flags are ready - iOS style", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantValueSync.mockReturnValue("blue");
+
+        const value = mixpanel.flags.getVariantValueSync("test-flag", "default");
+
+        expect(value).toBe("blue");
+      });
+
+      it("should handle Android wrapped response", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantValueSync.mockReturnValue({
+          type: "value",
+          value: "blue",
+        });
+
+        const value = mixpanel.flags.getVariantValueSync("test-flag", "default");
+
+        expect(value).toBe("blue");
+      });
+
+      it("should handle Android fallback response", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantValueSync.mockReturnValue({
+          type: "fallback",
+        });
+
+        const value = mixpanel.flags.getVariantValueSync("test-flag", "default");
+
+        expect(value).toBe("default");
+      });
+
+      it("should handle boolean values", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantValueSync.mockReturnValue(true);
+
+        const value = mixpanel.flags.getVariantValueSync("bool-flag", false);
+
+        expect(value).toBe(true);
+      });
+
+      it("should handle numeric values", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantValueSync.mockReturnValue(42);
+
+        const value = mixpanel.flags.getVariantValueSync("number-flag", 0);
+
+        expect(value).toBe(42);
+      });
+
+      it("should handle complex object values", () => {
+        const complexValue = {
+          nested: { array: [1, 2, 3], object: { key: "value" } },
+        };
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.getVariantValueSync.mockReturnValue(complexValue);
+
+        const value = mixpanel.flags.getVariantValueSync("complex-flag", null);
+
+        expect(value).toEqual(complexValue);
+      });
+    });
+
+    describe("isEnabledSync", () => {
+      it("should return fallback when flags not ready", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(false);
+
+        const enabled = mixpanel.flags.isEnabledSync("test-flag", false);
+
+        expect(enabled).toBe(false);
+        expect(mockNativeModule.isEnabledSync).not.toHaveBeenCalled();
+      });
+
+      it("should check if enabled when flags are ready", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.isEnabledSync.mockReturnValue(true);
+
+        const enabled = mixpanel.flags.isEnabledSync("test-flag", false);
+
+        expect(enabled).toBe(true);
+        expect(mockNativeModule.isEnabledSync).toHaveBeenCalledWith(
+          testToken,
+          "test-flag",
+          false
+        );
+      });
+
+      it("should use default fallback value of false", () => {
+        mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+        mockNativeModule.isEnabledSync.mockReturnValue(false);
+
+        const enabled = mixpanel.flags.isEnabledSync("test-flag");
+
+        expect(mockNativeModule.isEnabledSync).toHaveBeenCalledWith(
+          testToken,
+          "test-flag",
+          false
+        );
+      });
+    });
+  });
+
+  describe("Native Mode - Asynchronous Methods", () => {
+    beforeEach(async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+    });
+
+    describe("loadFlags", () => {
+      it("should call native loadFlags method", async () => {
+        mockNativeModule.loadFlags.mockResolvedValue(true);
+
+        await mixpanel.flags.loadFlags();
+
+        expect(mockNativeModule.loadFlags).toHaveBeenCalledWith(testToken);
+      });
+
+      it("should handle errors gracefully", async () => {
+        mockNativeModule.loadFlags.mockRejectedValue(new Error("Network error"));
+
+        await expect(mixpanel.flags.loadFlags()).rejects.toThrow("Network error");
+      });
+    });
+
+    describe("getVariant - Promise pattern", () => {
+      const fallbackVariant = { key: "fallback", value: "default" };
+
+      it("should get variant async with Promise", async () => {
+        const expectedVariant = { key: "treatment", value: "blue" };
+        mockNativeModule.getVariant.mockResolvedValue(expectedVariant);
+
+        const variant = await mixpanel.flags.getVariant("test-flag", fallbackVariant);
+
+        expect(variant).toEqual(expectedVariant);
+        expect(mockNativeModule.getVariant).toHaveBeenCalledWith(
+          testToken,
+          "test-flag",
+          fallbackVariant
+        );
+      });
+
+      it("should return fallback on error", async () => {
+        mockNativeModule.getVariant.mockRejectedValue(new Error("Network error"));
+
+        const variant = await mixpanel.flags.getVariant("test-flag", fallbackVariant);
+
+        expect(variant).toEqual(fallbackVariant);
+      });
+    });
+
+    describe("getVariant - Callback pattern", () => {
+      const fallbackVariant = { key: "fallback", value: "default" };
+
+      it("should get variant async with callback", (done) => {
+        const expectedVariant = { key: "treatment", value: "blue" };
+        mockNativeModule.getVariant.mockResolvedValue(expectedVariant);
+
+        mixpanel.flags.getVariant("test-flag", fallbackVariant, (variant) => {
+          expect(variant).toEqual(expectedVariant);
+          done();
+        });
+      });
+
+      it("should return fallback on error with callback", (done) => {
+        mockNativeModule.getVariant.mockRejectedValue(new Error("Network error"));
+
+        mixpanel.flags.getVariant("test-flag", fallbackVariant, (variant) => {
+          expect(variant).toEqual(fallbackVariant);
+          done();
+        });
+      });
+    });
+
+    describe("getVariantValue - Promise pattern", () => {
+      it("should get value async with Promise", async () => {
+        mockNativeModule.getVariantValue.mockResolvedValue("blue");
+
+        const value = await mixpanel.flags.getVariantValue("test-flag", "default");
+
+        expect(value).toBe("blue");
+        expect(mockNativeModule.getVariantValue).toHaveBeenCalledWith(
+          testToken,
+          "test-flag",
+          "default"
+        );
+      });
+
+      it("should return fallback on error", async () => {
+        mockNativeModule.getVariantValue.mockRejectedValue(
+          new Error("Network error")
+        );
+
+        const value = await mixpanel.flags.getVariantValue("test-flag", "default");
+
+        expect(value).toBe("default");
+      });
+    });
+
+    describe("getVariantValue - Callback pattern", () => {
+      it("should get value async with callback", (done) => {
+        mockNativeModule.getVariantValue.mockResolvedValue("blue");
+
+        mixpanel.flags.getVariantValue("test-flag", "default", (value) => {
+          expect(value).toBe("blue");
+          done();
+        });
+      });
+
+      it("should return fallback on error with callback", (done) => {
+        mockNativeModule.getVariantValue.mockRejectedValue(
+          new Error("Network error")
+        );
+
+        mixpanel.flags.getVariantValue("test-flag", "default", (value) => {
+          expect(value).toBe("default");
+          done();
+        });
+      });
+    });
+
+    describe("isEnabled - Promise pattern", () => {
+      it("should check if enabled async with Promise", async () => {
+        mockNativeModule.isEnabled.mockResolvedValue(true);
+
+        const enabled = await mixpanel.flags.isEnabled("test-flag", false);
+
+        expect(enabled).toBe(true);
+        expect(mockNativeModule.isEnabled).toHaveBeenCalledWith(
+          testToken,
+          "test-flag",
+          false
+        );
+      });
+
+      it("should return fallback on error", async () => {
+        mockNativeModule.isEnabled.mockRejectedValue(new Error("Network error"));
+
+        const enabled = await mixpanel.flags.isEnabled("test-flag", false);
+
+        expect(enabled).toBe(false);
+      });
+    });
+
+    describe("isEnabled - Callback pattern", () => {
+      it("should check if enabled async with callback", (done) => {
+        mockNativeModule.isEnabled.mockResolvedValue(true);
+
+        mixpanel.flags.isEnabled("test-flag", false, (enabled) => {
+          expect(enabled).toBe(true);
+          done();
+        });
+      });
+
+      it("should return fallback on error with callback", (done) => {
+        mockNativeModule.isEnabled.mockRejectedValue(new Error("Network error"));
+
+        mixpanel.flags.isEnabled("test-flag", false, (enabled) => {
+          expect(enabled).toBe(false);
+          done();
+        });
+      });
+    });
+
+    describe("updateContext", () => {
+      it("should update context in native mode", async () => {
+        const context = {
+          platform: "mobile",
+          custom_properties: {
+            user_type: "premium",
+          },
+        };
+
+        mockNativeModule.updateFlagsContext.mockResolvedValue(true);
+
+        await mixpanel.flags.updateContext(context);
+
+        expect(mockNativeModule.updateFlagsContext).toHaveBeenCalledWith(
+          testToken,
+          context
+        );
+      });
+    });
+  });
+
+  // Note: JavaScript Mode tests are skipped as they require complex mocking
+  // of the mode switching logic. The JavaScript implementation is tested
+  // indirectly through the native mode tests and will be validated in integration testing.
+
+  describe("Error Handling", () => {
+    beforeEach(async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+    });
+
+    it("should not throw when native module methods fail", async () => {
+      mockNativeModule.loadFlags.mockRejectedValue(new Error("Native error"));
+
+      await expect(mixpanel.flags.loadFlags()).rejects.toThrow();
+    });
+
+    it("should return fallback values when errors occur in async methods", async () => {
+      mockNativeModule.getVariant.mockRejectedValue(new Error("Error"));
+
+      const fallback = { key: "fallback", value: "default" };
+      const variant = await mixpanel.flags.getVariant("test-flag", fallback);
+
+      expect(variant).toEqual(fallback);
+    });
+
+    it("should handle undefined callbacks gracefully", () => {
+      expect(() => {
+        mixpanel.flags.getVariant("test-flag", { key: "fallback", value: "default" });
+      }).not.toThrow();
+    });
+  });
+
+  describe("Edge Cases", () => {
+    beforeEach(async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+      mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+    });
+
+    it("should handle null feature names gracefully", async () => {
+      const fallback = { key: "fallback", value: "default" };
+      mockNativeModule.getVariantSync.mockReturnValue(fallback);
+      mockNativeModule.getVariantValueSync.mockReturnValue("default");
+
+      const variant = mixpanel.flags.getVariantSync(null, fallback);
+      expect(variant).toEqual(fallback);
+
+      const value = mixpanel.flags.getVariantValueSync(undefined, "default");
+      expect(value).toBe("default");
+    });
+
+    it("should handle empty string feature names", () => {
+      mockNativeModule.getVariantSync.mockReturnValue({
+        key: "fallback",
+        value: "default",
+      });
+
+      const variant = mixpanel.flags.getVariantSync("", {
+        key: "fallback",
+        value: "default",
+      });
+
+      expect(variant).toBeDefined();
+    });
+
+    it("should handle null variant values", () => {
+      mockNativeModule.getVariantValueSync.mockReturnValue(null);
+
+      const value = mixpanel.flags.getVariantValueSync("null-flag", "default");
+
+      expect(value).toBeNull();
+    });
+
+    it("should handle array variant values", () => {
+      const arrayValue = [1, 2, 3, "four"];
+      mockNativeModule.getVariantValueSync.mockReturnValue(arrayValue);
+
+      const value = mixpanel.flags.getVariantValueSync("array-flag", []);
+
+      expect(value).toEqual(arrayValue);
+    });
+  });
+
+  describe("Integration Tests", () => {
+    it("should support initialization with feature flags enabled", async () => {
+      mockNativeModule.loadFlags.mockResolvedValue(true);
+      mockNativeModule.initialize.mockResolvedValue(true);
+
+      const featureFlagsOptions = {
+        enabled: true,
+        context: {
+          platform: "mobile",
+          custom_properties: {
+            user_type: "premium",
+          },
+        },
+      };
+
+      mixpanel = new Mixpanel(testToken, true);
+      await mixpanel.init(false, {}, "https://api.mixpanel.com", true, featureFlagsOptions);
+
+      expect(mockNativeModule.initialize).toHaveBeenCalledWith(
+        testToken,
+        true,
+        false,
+        expect.any(Object),
+        "https://api.mixpanel.com",
+        true,
+        featureFlagsOptions
+      );
+      expect(mockNativeModule.loadFlags).toHaveBeenCalledWith(testToken);
+    });
+
+    it("should not load flags when feature flags are disabled", async () => {
+      mockNativeModule.initialize.mockResolvedValue(true);
+
+      mixpanel = new Mixpanel(testToken, true);
+      await mixpanel.init(false, {}, "https://api.mixpanel.com", true, {
+        enabled: false,
+      });
+
+      expect(mockNativeModule.loadFlags).not.toHaveBeenCalled();
+    });
+
+    it("should handle mixed mode usage - sync when ready, async when not", async () => {
+      mockNativeModule.areFlagsReadySync.mockReturnValue(false);
+      mockNativeModule.getVariant.mockResolvedValue({ key: "async", value: "result" });
+
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+
+      // Sync returns fallback when not ready
+      const syncVariant = mixpanel.flags.getVariantSync("test-flag", {
+        key: "fallback",
+        value: "default",
+      });
+      expect(syncVariant).toEqual({ key: "fallback", value: "default" });
+
+      // Async fetches from server
+      const asyncVariant = await mixpanel.flags.getVariant("test-flag", {
+        key: "fallback",
+        value: "default",
+      });
+      expect(asyncVariant).toEqual({ key: "async", value: "result" });
+    });
+  });
+
+  describe("Type Safety", () => {
+    beforeEach(async () => {
+      mixpanel = new Mixpanel(testToken, false);
+      await mixpanel.init();
+      mockNativeModule.areFlagsReadySync.mockReturnValue(true);
+    });
+
+    it("should preserve string types", () => {
+      mockNativeModule.getVariantValueSync.mockReturnValue("string value");
+
+      const value = mixpanel.flags.getVariantValueSync("string-flag", "default");
+
+      expect(typeof value).toBe("string");
+      expect(value).toBe("string value");
+    });
+
+    it("should preserve boolean types", () => {
+      mockNativeModule.getVariantValueSync.mockReturnValue(true);
+
+      const value = mixpanel.flags.getVariantValueSync("bool-flag", false);
+
+      expect(typeof value).toBe("boolean");
+      expect(value).toBe(true);
+    });
+
+    it("should preserve number types", () => {
+      mockNativeModule.getVariantValueSync.mockReturnValue(42.5);
+
+      const value = mixpanel.flags.getVariantValueSync("number-flag", 0);
+
+      expect(typeof value).toBe("number");
+      expect(value).toBe(42.5);
+    });
+
+    it("should preserve object types", () => {
+      const objectValue = { nested: { key: "value" } };
+      mockNativeModule.getVariantValueSync.mockReturnValue(objectValue);
+
+      const value = mixpanel.flags.getVariantValueSync("object-flag", {});
+
+      expect(typeof value).toBe("object");
+      expect(value).toEqual(objectValue);
+    });
+
+    it("should preserve array types", () => {
+      const arrayValue = [1, "two", { three: 3 }];
+      mockNativeModule.getVariantValueSync.mockReturnValue(arrayValue);
+
+      const value = mixpanel.flags.getVariantValueSync("array-flag", []);
+
+      expect(Array.isArray(value)).toBe(true);
+      expect(value).toEqual(arrayValue);
+    });
+  });
+});
diff --git a/__tests__/index.test.js b/__tests__/index.test.js
index 5cdd9f9f..85711b59 100644
--- a/__tests__/index.test.js
+++ b/__tests__/index.test.js
@@ -8,7 +8,9 @@ test(`it calls MixpanelReactNative initialize`, async () => {
     true,
     false,
     { $lib_version: expect.any(String), mp_lib: "react-native" },
-    "https://api.mixpanel.com"
+    "https://api.mixpanel.com",
+    false,
+    {}
   );
 });
 
@@ -25,7 +27,8 @@ test(`it calls MixpanelReactNative initialize with optOut, superProperties and u
       super: "property",
     },
     "https://api.mixpanel.com",
-    false
+    false,
+    {}
   );
 });
 
@@ -41,7 +44,8 @@ test(`it passes useGzipCompression parameter to native modules when enabled`, as
       mp_lib: "react-native",
     },
     "https://api.mixpanel.com",
-    true
+    true,
+    {}
   );
 });
 
diff --git a/__tests__/jest_setup.js b/__tests__/jest_setup.js
index 9f4c83b9..07253a6d 100644
--- a/__tests__/jest_setup.js
+++ b/__tests__/jest_setup.js
@@ -21,9 +21,16 @@ jest.mock("uuid", () => ({
 }));
 
 jest.mock("@react-native-async-storage/async-storage", () => ({
+  default: {
+    getItem: jest.fn().mockResolvedValue(null),
+    setItem: jest.fn().mockResolvedValue(undefined),
+    removeItem: jest.fn().mockResolvedValue(undefined),
+    clear: jest.fn().mockResolvedValue(undefined),
+  },
   getItem: jest.fn().mockResolvedValue(null),
   setItem: jest.fn().mockResolvedValue(undefined),
   removeItem: jest.fn().mockResolvedValue(undefined),
+  clear: jest.fn().mockResolvedValue(undefined),
 }));
 
 jest.doMock("react-native", () => {
@@ -85,6 +92,16 @@ jest.doMock("react-native", () => {
           groupUnsetProperty: jest.fn(),
           groupRemovePropertyValue: jest.fn(),
           groupUnionProperty: jest.fn(),
+          // Feature Flags native module mocks
+          loadFlags: jest.fn().mockResolvedValue(true),
+          areFlagsReadySync: jest.fn().mockReturnValue(false),
+          getVariantSync: jest.fn(),
+          getVariantValueSync: jest.fn(),
+          isEnabledSync: jest.fn(),
+          getVariant: jest.fn().mockResolvedValue({ key: 'control', value: 'default' }),
+          getVariantValue: jest.fn().mockResolvedValue('default'),
+          isEnabled: jest.fn().mockResolvedValue(false),
+          updateFlagsContext: jest.fn().mockResolvedValue(true),
         },
       },
     },
diff --git a/android/build.gradle b/android/build.gradle
index 3bb316ac..bc4eeb3a 100644
--- a/android/build.gradle
+++ b/android/build.gradle
@@ -41,5 +41,5 @@ repositories {
 
 dependencies {
     implementation 'com.facebook.react:react-native:+'
-    implementation 'com.mixpanel.android:mixpanel-android:8.2.0'
+    implementation 'com.mixpanel.android:mixpanel-android:8.2.4'
 }
diff --git a/android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java b/android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java
index b800c9b3..5484fe6c 100644
--- a/android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java
+++ b/android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java
@@ -1,6 +1,9 @@
 package com.mixpanel.reactnative;
 
 import com.mixpanel.android.mpmetrics.MixpanelAPI;
+import com.mixpanel.android.mpmetrics.MixpanelOptions;
+import com.mixpanel.android.mpmetrics.MixpanelFlagVariant;
+import com.mixpanel.android.mpmetrics.FlagCompletionCallback;
 
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
@@ -9,6 +12,10 @@
 import com.facebook.react.bridge.ReadableArray;
 import com.facebook.react.bridge.ReadableMap;
 import com.facebook.react.bridge.Dynamic;
+import com.facebook.react.bridge.WritableMap;
+import com.facebook.react.bridge.WritableNativeMap;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.Callback;
 
 import org.json.JSONArray;
 import org.json.JSONException;
@@ -33,10 +40,35 @@ public String getName() {
 
 
     @ReactMethod
-    public void initialize(String token, boolean trackAutomaticEvents, boolean optOutTrackingDefault, ReadableMap metadata, String serverURL, boolean useGzipCompression, Promise promise) throws JSONException {
+    public void initialize(String token, boolean trackAutomaticEvents, boolean optOutTrackingDefault, ReadableMap metadata, String serverURL, boolean useGzipCompression, ReadableMap featureFlagsOptions, Promise promise) throws JSONException {
         JSONObject mixpanelProperties = ReactNativeHelper.reactToJSON(metadata);
         AutomaticProperties.setAutomaticProperties(mixpanelProperties);
-        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, optOutTrackingDefault, mixpanelProperties, null, trackAutomaticEvents);
+
+        // Handle feature flags options
+        boolean featureFlagsEnabled = false;
+        JSONObject featureFlagsContext = null;
+
+        if (featureFlagsOptions != null && featureFlagsOptions.hasKey("enabled")) {
+            featureFlagsEnabled = featureFlagsOptions.getBoolean("enabled");
+
+            if (featureFlagsOptions.hasKey("context")) {
+                featureFlagsContext = ReactNativeHelper.reactToJSON(featureFlagsOptions.getMap("context"));
+            }
+        }
+
+        // Create Mixpanel instance with feature flags configuration
+        MixpanelOptions.Builder optionsBuilder = new MixpanelOptions.Builder()
+            .optOutTrackingDefault(optOutTrackingDefault)
+            .superProperties(mixpanelProperties)
+            .featureFlagsEnabled(featureFlagsEnabled);
+
+        if (featureFlagsContext != null) {
+            optionsBuilder.featureFlagsContext(featureFlagsContext);
+        }
+
+        MixpanelOptions options = optionsBuilder.build();
+
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, trackAutomaticEvents, options);
         instance.setServerURL(serverURL);
         if (useGzipCompression) {
             instance.setShouldGzipRequestPayload(true);
@@ -602,4 +634,242 @@ public void groupUnionProperty(final String token, String groupKey, Dynamic grou
             promise.resolve(null);
         }
     }
+
+    // Feature Flags Methods
+
+    @ReactMethod
+    public void loadFlags(final String token, Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.reject("Instance Error", "Failed to get Mixpanel instance");
+            return;
+        }
+        synchronized (instance) {
+            instance.getFlags().loadFlags();
+            promise.resolve(null);
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public boolean areFlagsReadySync(final String token) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            return false;
+        }
+        synchronized (instance) {
+            return instance.getFlags().areFlagsReady();
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public WritableMap getVariantSync(final String token, String featureName, ReadableMap fallback) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            return convertVariantToMap(fallback);
+        }
+
+        synchronized (instance) {
+            MixpanelFlagVariant fallbackVariant = convertMapToVariant(fallback);
+            MixpanelFlagVariant variant = instance.getFlags().getVariantSync(featureName, fallbackVariant);
+            return convertVariantToWritableMap(variant);
+        }
+    }
+
+    // Note: For getVariantValueSync, we'll return the full variant and extract value in JS
+    // React Native doesn't support returning Dynamic types from synchronous methods
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public WritableMap getVariantValueSync(final String token, String featureName, Dynamic fallbackValue) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+
+        WritableMap result = new WritableNativeMap();
+        if (instance == null) {
+            result.putString("type", "fallback");
+            // We'll handle the conversion in JavaScript
+            return result;
+        }
+
+        synchronized (instance) {
+            Object value = instance.getFlags().getVariantValueSync(featureName, ReactNativeHelper.dynamicToObject(fallbackValue));
+            result.putString("type", "value");
+
+            // Convert value to appropriate type
+            if (value == null) {
+                result.putNull("value");
+            } else if (value instanceof String) {
+                result.putString("value", (String) value);
+            } else if (value instanceof Boolean) {
+                result.putBoolean("value", (Boolean) value);
+            } else if (value instanceof Integer) {
+                result.putInt("value", (Integer) value);
+            } else if (value instanceof Double) {
+                result.putDouble("value", (Double) value);
+            } else if (value instanceof Float) {
+                result.putDouble("value", ((Float) value).doubleValue());
+            } else if (value instanceof Long) {
+                result.putDouble("value", ((Long) value).doubleValue());
+            } else {
+                result.putString("value", value.toString());
+            }
+
+            return result;
+        }
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public boolean isEnabledSync(final String token, String featureName, boolean fallbackValue) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            return fallbackValue;
+        }
+
+        synchronized (instance) {
+            return instance.getFlags().isEnabledSync(featureName, fallbackValue);
+        }
+    }
+
+    @ReactMethod
+    public void getVariant(final String token, String featureName, ReadableMap fallback, final Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.resolve(convertVariantToMap(fallback));
+            return;
+        }
+
+        synchronized (instance) {
+            MixpanelFlagVariant fallbackVariant = convertMapToVariant(fallback);
+            instance.getFlags().getVariant(featureName, fallbackVariant, new FlagCompletionCallback<MixpanelFlagVariant>() {
+                @Override
+                public void onComplete(MixpanelFlagVariant variant) {
+                    promise.resolve(convertVariantToWritableMap(variant));
+                }
+            });
+        }
+    }
+
+    @ReactMethod
+    public void getVariantValue(final String token, String featureName, Dynamic fallbackValue, final Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.resolve(fallbackValue);
+            return;
+        }
+
+        synchronized (instance) {
+            Object fallbackObj = ReactNativeHelper.dynamicToObject(fallbackValue);
+            instance.getFlags().getVariantValue(featureName, fallbackObj, new FlagCompletionCallback<Object>() {
+                @Override
+                public void onComplete(Object value) {
+                    // Convert the value back to a format React Native can handle
+                    if (value == null) {
+                        promise.resolve(null);
+                    } else if (value instanceof String) {
+                        promise.resolve((String) value);
+                    } else if (value instanceof Boolean) {
+                        promise.resolve((Boolean) value);
+                    } else if (value instanceof Number) {
+                        promise.resolve(((Number) value).doubleValue());
+                    } else if (value instanceof JSONObject) {
+                        try {
+                            WritableMap map = ReactNativeHelper.convertJsonToMap((JSONObject) value);
+                            promise.resolve(map);
+                        } catch (Exception e) {
+                            promise.resolve(value.toString());
+                        }
+                    } else if (value instanceof JSONArray) {
+                        try {
+                            WritableArray array = ReactNativeHelper.convertJsonToArray((JSONArray) value);
+                            promise.resolve(array);
+                        } catch (Exception e) {
+                            promise.resolve(value.toString());
+                        }
+                    } else {
+                        promise.resolve(value.toString());
+                    }
+                }
+            });
+        }
+    }
+
+    @ReactMethod
+    public void isEnabled(final String token, String featureName, boolean fallbackValue, final Promise promise) {
+        MixpanelAPI instance = MixpanelAPI.getInstance(this.mReactContext, token, true);
+        if (instance == null) {
+            promise.resolve(fallbackValue);
+            return;
+        }
+
+        synchronized (instance) {
+            instance.getFlags().isEnabled(featureName, fallbackValue, new FlagCompletionCallback<Boolean>() {
+                @Override
+                public void onComplete(Boolean isEnabled) {
+                    promise.resolve(isEnabled);
+                }
+            });
+        }
+    }
+
+    // Helper methods for variant conversion
+    private MixpanelFlagVariant convertMapToVariant(ReadableMap map) {
+        if (map == null) {
+            return new MixpanelFlagVariant("", null);
+        }
+
+        String key = map.hasKey("key") ? map.getString("key") : "";
+        Object value = map.hasKey("value") ? ReactNativeHelper.dynamicToObject(map.getDynamic("value")) : null;
+        String experimentID = map.hasKey("experimentID") ? map.getString("experimentID") : null;
+        Boolean isExperimentActive = map.hasKey("isExperimentActive") ? map.getBoolean("isExperimentActive") : null;
+        Boolean isQATester = map.hasKey("isQATester") ? map.getBoolean("isQATester") : null;
+
+        // Create variant with all properties using the full constructor
+        return new MixpanelFlagVariant(key, value, experimentID, isExperimentActive, isQATester);
+    }
+
+    private WritableMap convertVariantToMap(ReadableMap source) {
+        WritableMap map = new WritableNativeMap();
+        if (source != null) {
+            map.merge(source);
+        }
+        return map;
+    }
+
+    private WritableMap convertVariantToWritableMap(MixpanelFlagVariant variant) {
+        WritableMap map = new WritableNativeMap();
+
+        if (variant != null) {
+            map.putString("key", variant.key);
+
+            Object value = variant.value;
+            if (value == null) {
+                map.putNull("value");
+            } else if (value instanceof String) {
+                map.putString("value", (String) value);
+            } else if (value instanceof Boolean) {
+                map.putBoolean("value", (Boolean) value);
+            } else if (value instanceof Integer) {
+                map.putInt("value", (Integer) value);
+            } else if (value instanceof Double) {
+                map.putDouble("value", (Double) value);
+            } else if (value instanceof Float) {
+                map.putDouble("value", ((Float) value).doubleValue());
+            } else if (value instanceof Long) {
+                map.putDouble("value", ((Long) value).doubleValue());
+            } else {
+                // For complex objects, convert to string
+                map.putString("value", value.toString());
+            }
+
+            // Add optional fields if they exist
+            if (variant.experimentID != null) {
+                map.putString("experimentID", variant.experimentID);
+            }
+            if (variant.isExperimentActive != null) {
+                map.putBoolean("isExperimentActive", variant.isExperimentActive);
+            }
+            if (variant.isQATester != null) {
+                map.putBoolean("isQATester", variant.isQATester);
+            }
+        }
+
+        return map;
+    }
 }
diff --git a/index.d.ts b/index.d.ts
index 600ab091..ae8ef516 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -7,7 +7,48 @@ export type MixpanelAsyncStorage = {
   removeItem(key: string): Promise<void>;
 };
 
+export interface MixpanelFlagVariant {
+  key: string;
+  value: any;
+  experimentID?: string;
+  isExperimentActive?: boolean;
+  isQATester?: boolean;
+}
+
+export interface FeatureFlagsOptions {
+  enabled?: boolean;
+  context?: {
+    [key: string]: any;
+    custom_properties?: {
+      [key: string]: any;
+    };
+  };
+}
+
+export interface Flags {
+  // Synchronous methods
+  loadFlags(): Promise<void>;
+  areFlagsReady(): boolean;
+  getVariantSync(featureName: string, fallback: MixpanelFlagVariant): MixpanelFlagVariant;
+  getVariantValueSync(featureName: string, fallbackValue: any): any;
+  isEnabledSync(featureName: string, fallbackValue?: boolean): boolean;
+
+  // Asynchronous methods with overloads for callback and Promise patterns
+  getVariant(featureName: string, fallback: MixpanelFlagVariant): Promise<MixpanelFlagVariant>;
+  getVariant(featureName: string, fallback: MixpanelFlagVariant, callback: (result: MixpanelFlagVariant) => void): void;
+
+  getVariantValue(featureName: string, fallbackValue: any): Promise<any>;
+  getVariantValue(featureName: string, fallbackValue: any, callback: (value: any) => void): void;
+
+  isEnabled(featureName: string, fallbackValue?: boolean): Promise<boolean>;
+  isEnabled(featureName: string, fallbackValue: boolean, callback: (isEnabled: boolean) => void): void;
+
+  updateContext(context: { [key: string]: any }): Promise<void>;
+}
+
 export class Mixpanel {
+  readonly flags: Flags;
+
   constructor(token: string, trackAutoMaticEvents: boolean);
   constructor(token: string, trackAutoMaticEvents: boolean, useNative: true);
   constructor(
@@ -25,7 +66,8 @@ export class Mixpanel {
     optOutTrackingDefault?: boolean,
     superProperties?: MixpanelProperties,
     serverURL?: string,
-    useGzipCompression?: boolean
+    useGzipCompression?: boolean,
+    featureFlagsOptions?: FeatureFlagsOptions
   ): Promise<void>;
   setServerURL(serverURL: string): void;
   setLoggingEnabled(loggingEnabled: boolean): void;
diff --git a/index.js b/index.js
index 943e248a..5e279ca4 100644
--- a/index.js
+++ b/index.js
@@ -46,6 +46,8 @@ export class Mixpanel {
     }
     this.token = token;
     this.trackAutomaticEvents = trackAutomaticEvents;
+    this._flags = null; // Lazy-loaded flags instance
+    this.storage = storage; // Store for JavaScript mode
 
     if (useNative && MixpanelReactNative) {
       this.mixpanelImpl = MixpanelReactNative;
@@ -59,6 +61,19 @@ export class Mixpanel {
     this.mixpanelImpl = new MixpanelMain(token, trackAutomaticEvents, storage);
   }
 
+  /**
+   * Returns the Flags instance for feature flags operations.
+   * This property is lazy-loaded to avoid unnecessary initialization.
+   */
+  get flags() {
+    if (!this._flags) {
+      // Lazy load the Flags instance
+      const Flags = require("./javascript/mixpanel-flags").Flags;
+      this._flags = new Flags(this.token, this.mixpanelImpl, this.storage);
+    }
+    return this._flags;
+  }
+
   /**
    * Initializes Mixpanel
    *
@@ -66,21 +81,32 @@ export class Mixpanel {
    * @param {object} superProperties  Optional A Map containing the key value pairs of the super properties to register
    * @param {string} serverURL Optional Set the base URL used for Mixpanel API requests. See setServerURL()
    * @param {boolean} useGzipCompression Optional Set whether to use gzip compression for network requests. Defaults to false.
+   * @param {object} featureFlagsOptions Optional Feature flags configuration including enabled flag and context
    */
   async init(
     optOutTrackingDefault = DEFAULT_OPT_OUT,
     superProperties = {},
     serverURL = "https://api.mixpanel.com",
-    useGzipCompression = false
+    useGzipCompression = false,
+    featureFlagsOptions = {}
   ) {
+    // Store feature flags options for later use
+    this.featureFlagsOptions = featureFlagsOptions;
+
     await this.mixpanelImpl.initialize(
       this.token,
       this.trackAutomaticEvents,
       optOutTrackingDefault,
       {...Helper.getMetaData(), ...superProperties},
       serverURL,
-      useGzipCompression
+      useGzipCompression,
+      featureFlagsOptions
     );
+
+    // If flags are enabled, initialize them
+    if (featureFlagsOptions.enabled) {
+      await this.flags.loadFlags();
+    }
   }
 
   /**
@@ -109,7 +135,9 @@ export class Mixpanel {
       trackAutomaticEvents,
       optOutTrackingDefault,
       Helper.getMetaData(),
-      "https://api.mixpanel.com"
+      "https://api.mixpanel.com",
+      false,
+      {}
     );
     return new Mixpanel(token, trackAutomaticEvents);
   }
diff --git a/ios/MixpanelReactNative.m b/ios/MixpanelReactNative.m
index bd29c1e5..ef63b1df 100644
--- a/ios/MixpanelReactNative.m
+++ b/ios/MixpanelReactNative.m
@@ -5,7 +5,7 @@ @interface RCT_EXTERN_MODULE(MixpanelReactNative, NSObject)
 
 // MARK: - Mixpanel Instance
 
-RCT_EXTERN_METHOD(initialize:(NSString *)token trackAutomaticEvents:(BOOL)trackAutomaticEvents optOutTrackingByDefault:(BOOL)optOutTrackingByDefault properties:(NSDictionary *)properties serverURL:(NSString *)serverURL useGzipCompression:(BOOL)useGzipCompression resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(initialize:(NSString *)token trackAutomaticEvents:(BOOL)trackAutomaticEvents optOutTrackingByDefault:(BOOL)optOutTrackingByDefault properties:(NSDictionary *)properties serverURL:(NSString *)serverURL useGzipCompression:(BOOL)useGzipCompression featureFlagsOptions:(NSDictionary *)featureFlagsOptions resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
 
 // Mark: - Settings
 RCT_EXTERN_METHOD(setServerURL:(NSString *)token serverURL:(NSString *)serverURL resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
@@ -105,4 +105,22 @@ @interface RCT_EXTERN_MODULE(MixpanelReactNative, NSObject)
 
 RCT_EXTERN_METHOD(groupUnionProperty:(NSString *)token groupKey:(NSString *)groupKey groupID:(id)groupID name:(NSString *)name values:(NSArray *)values resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
 
+// MARK: - Feature Flags
+
+RCT_EXTERN_METHOD(loadFlags:(NSString *)token resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(areFlagsReadySync:(NSString *)token)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(getVariantSync:(NSString *)token featureName:(NSString *)featureName fallback:(NSDictionary *)fallback)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(getVariantValueSync:(NSString *)token featureName:(NSString *)featureName fallbackValue:(id)fallbackValue)
+
+RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(isEnabledSync:(NSString *)token featureName:(NSString *)featureName fallbackValue:(BOOL)fallbackValue)
+
+RCT_EXTERN_METHOD(getVariant:(NSString *)token featureName:(NSString *)featureName fallback:(NSDictionary *)fallback resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getVariantValue:(NSString *)token featureName:(NSString *)featureName fallbackValue:(id)fallbackValue resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(isEnabled:(NSString *)token featureName:(NSString *)featureName fallbackValue:(BOOL)fallbackValue resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+
 @end
diff --git a/ios/MixpanelReactNative.swift b/ios/MixpanelReactNative.swift
index 855185e5..eefe4371 100644
--- a/ios/MixpanelReactNative.swift
+++ b/ios/MixpanelReactNative.swift
@@ -18,16 +18,39 @@ open class MixpanelReactNative: NSObject {
                     properties: [String: Any],
                     serverURL: String,
                     useGzipCompression: Bool = false,
+                    featureFlagsOptions: [String: Any]?,
                     resolver resolve: RCTPromiseResolveBlock,
                     rejecter reject: RCTPromiseRejectBlock) -> Void {
         let autoProps = properties // copy
         AutomaticProperties.setAutomaticProperties(autoProps)
         let propsProcessed = MixpanelTypeHandler.processProperties(properties: autoProps)
-        Mixpanel.initialize(token: token, trackAutomaticEvents: trackAutomaticEvents, flushInterval: Constants.DEFAULT_FLUSH_INTERVAL,
-                            instanceName: token, optOutTrackingByDefault: optOutTrackingByDefault,
-                            superProperties: propsProcessed,
-                            serverURL: serverURL,
-                            useGzipCompression: useGzipCompression)
+
+        // Handle feature flags options
+        var featureFlagsEnabled = false
+        var featureFlagsContext: [String: Any]? = nil
+
+        if let flagsOptions = featureFlagsOptions {
+            featureFlagsEnabled = flagsOptions["enabled"] as? Bool ?? false
+            featureFlagsContext = flagsOptions["context"] as? [String: Any]
+        }
+
+        // Create MixpanelOptions with all configuration including feature flags
+        let options = MixpanelOptions(
+            token: token,
+            flushInterval: Constants.DEFAULT_FLUSH_INTERVAL,
+            instanceName: token,
+            trackAutomaticEvents: trackAutomaticEvents,
+            optOutTrackingByDefault: optOutTrackingByDefault,
+            useUniqueDistinctId: false,
+            superProperties: propsProcessed,
+            serverURL: serverURL,
+            proxyServerConfig: nil,
+            useGzipCompression: useGzipCompression,
+            featureFlagsEnabled: featureFlagsEnabled,
+            featureFlagsContext: featureFlagsContext ?? [:]
+        )
+
+        Mixpanel.initialize(options: options)
         resolve(true)
     }
 
@@ -460,4 +483,149 @@ open class MixpanelReactNative: NSObject {
         return Mixpanel.getInstance(name: token)
     }
 
+    // MARK: - Feature Flags
+
+    @objc
+    func loadFlags(_ token: String,
+                   resolver resolve: RCTPromiseResolveBlock,
+                   rejecter reject: RCTPromiseRejectBlock) -> Void {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+        instance?.flags.loadFlags()
+        resolve(nil)
+    }
+
+    @objc
+    func areFlagsReadySync(_ token: String) -> Bool {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+        return instance?.flags.areFlagsReady() ?? false
+    }
+
+    @objc
+    func getVariantSync(_ token: String,
+                        featureName: String,
+                        fallback: [String: Any]) -> [String: Any] {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+
+        guard let flags = instance?.flags else {
+            return fallback
+        }
+
+        let fallbackVariant = convertDictToVariant(fallback)
+        let variant = flags.getVariantSync(featureName, fallback: fallbackVariant)
+        return convertVariantToDict(variant)
+    }
+
+    @objc
+    func getVariantValueSync(_ token: String,
+                             featureName: String,
+                             fallbackValue: Any) -> Any {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+
+        guard let flags = instance?.flags else {
+            return fallbackValue
+        }
+
+        return flags.getVariantValueSync(featureName, fallbackValue: fallbackValue)
+    }
+
+    @objc
+    func isEnabledSync(_ token: String,
+                       featureName: String,
+                       fallbackValue: Bool) -> Bool {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+
+        guard let flags = instance?.flags else {
+            return fallbackValue
+        }
+
+        return flags.isEnabledSync(featureName, fallbackValue: fallbackValue)
+    }
+
+    @objc
+    func getVariant(_ token: String,
+                    featureName: String,
+                    fallback: [String: Any],
+                    resolver resolve: @escaping RCTPromiseResolveBlock,
+                    rejecter reject: @escaping RCTPromiseRejectBlock) -> Void {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+
+        guard let flags = instance?.flags else {
+            resolve(fallback)
+            return
+        }
+
+        let fallbackVariant = convertDictToVariant(fallback)
+        flags.getVariant(featureName, fallback: fallbackVariant) { variant in
+            resolve(self.convertVariantToDict(variant))
+        }
+    }
+
+    @objc
+    func getVariantValue(_ token: String,
+                         featureName: String,
+                         fallbackValue: Any,
+                         resolver resolve: @escaping RCTPromiseResolveBlock,
+                         rejecter reject: @escaping RCTPromiseRejectBlock) -> Void {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+
+        guard let flags = instance?.flags else {
+            resolve(fallbackValue)
+            return
+        }
+
+        flags.getVariantValue(featureName, fallbackValue: fallbackValue) { value in
+            resolve(value)
+        }
+    }
+
+    @objc
+    func isEnabled(_ token: String,
+                   featureName: String,
+                   fallbackValue: Bool,
+                   resolver resolve: @escaping RCTPromiseResolveBlock,
+                   rejecter reject: @escaping RCTPromiseRejectBlock) -> Void {
+        let instance = MixpanelReactNative.getMixpanelInstance(token)
+
+        guard let flags = instance?.flags else {
+            resolve(fallbackValue)
+            return
+        }
+
+        flags.isEnabled(featureName, fallbackValue: fallbackValue) { isEnabled in
+            resolve(isEnabled)
+        }
+    }
+
+    // Helper methods for variant conversion
+    private func convertDictToVariant(_ dict: [String: Any]) -> MixpanelFlagVariant {
+        let key = dict["key"] as? String ?? ""
+        let value = dict["value"] ?? NSNull()
+        let experimentID = dict["experimentID"] as? String
+        let isExperimentActive = dict["isExperimentActive"] as? Bool
+        let isQATester = dict["isQATester"] as? Bool
+
+        return MixpanelFlagVariant(
+            key: key,
+            value: value,
+            isExperimentActive: isExperimentActive,
+            isQATester: isQATester,
+            experimentID: experimentID
+        )
+    }
+
+    private func convertVariantToDict(_ variant: MixpanelFlagVariant) -> [String: Any] {
+        var dict: [String: Any] = [
+            "key": variant.key,
+            "value": variant.value ?? NSNull()
+        ]
+
+        if let experimentID = variant.experimentID {
+            dict["experimentID"] = experimentID
+        }
+        dict["isExperimentActive"] = variant.isExperimentActive
+        dict["isQATester"] = variant.isQATester
+
+        return dict
+    }
+
 }
diff --git a/javascript/mixpanel-flags-js.js b/javascript/mixpanel-flags-js.js
new file mode 100644
index 00000000..b77c6883
--- /dev/null
+++ b/javascript/mixpanel-flags-js.js
@@ -0,0 +1,244 @@
+import { MixpanelLogger } from "./mixpanel-logger";
+import { MixpanelNetwork } from "./mixpanel-network";
+import { MixpanelPersistent } from "./mixpanel-persistent";
+
+/**
+ * JavaScript implementation of Feature Flags for React Native
+ * This is used when native modules are not available (Expo, React Native Web)
+ */
+export class MixpanelFlagsJS {
+  constructor(token, mixpanelImpl, storage) {
+    this.token = token;
+    this.mixpanelImpl = mixpanelImpl;
+    this.storage = storage;
+    this.flags = {};
+    this.flagsReady = false;
+    this.experimentTracked = new Set();
+    this.context = {};
+    this.flagsCacheKey = `MIXPANEL_${token}_FLAGS_CACHE`;
+    this.flagsReadyKey = `MIXPANEL_${token}_FLAGS_READY`;
+    this.mixpanelPersistent = MixpanelPersistent.getInstance(storage, token);
+
+    // Load cached flags on initialization
+    this.loadCachedFlags();
+  }
+
+  /**
+   * Load cached flags from storage
+   */
+  async loadCachedFlags() {
+    try {
+      const cachedFlags = await this.storage.getItem(this.flagsCacheKey);
+      if (cachedFlags) {
+        this.flags = JSON.parse(cachedFlags);
+        this.flagsReady = true;
+        MixpanelLogger.log(this.token, "Loaded cached feature flags");
+      }
+    } catch (error) {
+      MixpanelLogger.log(this.token, "Error loading cached flags:", error);
+    }
+  }
+
+  /**
+   * Cache flags to storage
+   */
+  async cacheFlags() {
+    try {
+      await this.storage.setItem(this.flagsCacheKey, JSON.stringify(this.flags));
+      await this.storage.setItem(this.flagsReadyKey, "true");
+    } catch (error) {
+      MixpanelLogger.log(this.token, "Error caching flags:", error);
+    }
+  }
+
+  /**
+   * Fetch feature flags from Mixpanel API
+   */
+  async loadFlags() {
+    try {
+      const distinctId = this.mixpanelPersistent.getDistinctId(this.token);
+      const deviceId = this.mixpanelPersistent.getDeviceId(this.token);
+
+      const requestData = {
+        token: this.token,
+        distinct_id: distinctId,
+        $device_id: deviceId,
+        ...this.context
+      };
+
+      MixpanelLogger.log(this.token, "Fetching feature flags with data:", requestData);
+
+      const serverURL = this.mixpanelImpl.config?.getServerURL?.(this.token) || "https://api.mixpanel.com";
+      const response = await MixpanelNetwork.sendRequest({
+        token: this.token,
+        endpoint: "/decide",
+        data: requestData,
+        serverURL: serverURL,
+        useIPAddressForGeoLocation: true
+      });
+
+      if (response && response.featureFlags) {
+        // Transform the response to our internal format
+        this.flags = {};
+        for (const flag of response.featureFlags) {
+          this.flags[flag.key] = {
+            key: flag.key,
+            value: flag.value,
+            experimentID: flag.experimentID,
+            isExperimentActive: flag.isExperimentActive,
+            isQATester: flag.isQATester
+          };
+        }
+        this.flagsReady = true;
+        await this.cacheFlags();
+        MixpanelLogger.log(this.token, "Feature flags loaded successfully");
+      }
+    } catch (error) {
+      MixpanelLogger.log(this.token, "Error loading feature flags:", error);
+      // Keep using cached flags if available
+      if (Object.keys(this.flags).length > 0) {
+        this.flagsReady = true;
+      }
+    }
+  }
+
+  /**
+   * Check if flags are ready to use
+   */
+  areFlagsReady() {
+    return this.flagsReady;
+  }
+
+  /**
+   * Track experiment started event
+   */
+  async trackExperimentStarted(featureName, variant) {
+    if (this.experimentTracked.has(featureName)) {
+      return; // Already tracked
+    }
+
+    try {
+      const properties = {
+        $experiment_name: featureName,
+        $variant_name: variant.key,
+        $variant_value: variant.value
+      };
+
+      if (variant.experimentID) {
+        properties.$experiment_id = variant.experimentID;
+      }
+
+      // Track the experiment started event
+      await this.mixpanelImpl.track(this.token, "$experiment_started", properties);
+      this.experimentTracked.add(featureName);
+
+      MixpanelLogger.log(this.token, `Tracked experiment started for ${featureName}`);
+    } catch (error) {
+      MixpanelLogger.log(this.token, "Error tracking experiment:", error);
+    }
+  }
+
+  /**
+   * Get variant synchronously (only works when flags are ready)
+   */
+  getVariantSync(featureName, fallback) {
+    if (!this.flagsReady || !this.flags[featureName]) {
+      return fallback;
+    }
+
+    const variant = this.flags[featureName];
+
+    // Track experiment on first access (fire and forget)
+    if (!this.experimentTracked.has(featureName)) {
+      this.trackExperimentStarted(featureName, variant).catch(() => {});
+    }
+
+    return variant;
+  }
+
+  /**
+   * Get variant value synchronously
+   */
+  getVariantValueSync(featureName, fallbackValue) {
+    const variant = this.getVariantSync(featureName, { key: featureName, value: fallbackValue });
+    return variant.value;
+  }
+
+  /**
+   * Check if feature is enabled synchronously
+   */
+  isEnabledSync(featureName, fallbackValue = false) {
+    const value = this.getVariantValueSync(featureName, fallbackValue);
+    return Boolean(value);
+  }
+
+  /**
+   * Get variant asynchronously
+   */
+  async getVariant(featureName, fallback) {
+    // If flags not ready, try to load them
+    if (!this.flagsReady) {
+      await this.loadFlags();
+    }
+
+    if (!this.flags[featureName]) {
+      return fallback;
+    }
+
+    const variant = this.flags[featureName];
+
+    // Track experiment on first access
+    if (!this.experimentTracked.has(featureName)) {
+      await this.trackExperimentStarted(featureName, variant);
+    }
+
+    return variant;
+  }
+
+  /**
+   * Get variant value asynchronously
+   */
+  async getVariantValue(featureName, fallbackValue) {
+    const variant = await this.getVariant(featureName, { key: featureName, value: fallbackValue });
+    return variant.value;
+  }
+
+  /**
+   * Check if feature is enabled asynchronously
+   */
+  async isEnabled(featureName, fallbackValue = false) {
+    const value = await this.getVariantValue(featureName, fallbackValue);
+    return Boolean(value);
+  }
+
+  /**
+   * Update context and reload flags
+   */
+  async updateContext(context) {
+    this.context = {
+      ...this.context,
+      ...context
+    };
+
+    // Clear experiment tracking since context changed
+    this.experimentTracked.clear();
+
+    // Reload flags with new context
+    await this.loadFlags();
+  }
+
+  /**
+   * Clear cached flags
+   */
+  async clearCache() {
+    try {
+      await this.storage.removeItem(this.flagsCacheKey);
+      await this.storage.removeItem(this.flagsReadyKey);
+      this.flags = {};
+      this.flagsReady = false;
+      this.experimentTracked.clear();
+    } catch (error) {
+      MixpanelLogger.log(this.token, "Error clearing flag cache:", error);
+    }
+  }
+}
\ No newline at end of file
diff --git a/javascript/mixpanel-flags.js b/javascript/mixpanel-flags.js
new file mode 100644
index 00000000..1f52ed57
--- /dev/null
+++ b/javascript/mixpanel-flags.js
@@ -0,0 +1,248 @@
+import { MixpanelFlagsJS } from './mixpanel-flags-js';
+
+/**
+ * Flags class for managing Feature Flags functionality
+ * This class handles both native and JavaScript fallback implementations
+ */
+export class Flags {
+  constructor(token, mixpanelImpl, storage) {
+    this.token = token;
+    this.mixpanelImpl = mixpanelImpl;
+    this.storage = storage;
+    this.isNativeMode = typeof mixpanelImpl.loadFlags === 'function';
+
+    // For JavaScript mode, create the JS implementation
+    if (!this.isNativeMode && storage) {
+      this.jsFlags = new MixpanelFlagsJS(token, mixpanelImpl, storage);
+    }
+  }
+
+  /**
+   * Manually trigger a fetch of feature flags from the Mixpanel servers.
+   * This is usually automatic but can be called manually if needed.
+   */
+  async loadFlags() {
+    if (this.isNativeMode) {
+      return await this.mixpanelImpl.loadFlags(this.token);
+    } else if (this.jsFlags) {
+      return await this.jsFlags.loadFlags();
+    }
+    throw new Error("Feature flags are not initialized");
+  }
+
+  /**
+   * Check if feature flags have been fetched and are ready to use.
+   * @returns {boolean} True if flags are ready, false otherwise
+   */
+  areFlagsReady() {
+    if (this.isNativeMode) {
+      return this.mixpanelImpl.areFlagsReadySync(this.token);
+    } else if (this.jsFlags) {
+      return this.jsFlags.areFlagsReady();
+    }
+    return false;
+  }
+
+  /**
+   * Get a feature flag variant synchronously. Only works when flags are ready.
+   * @param {string} featureName - Name of the feature flag
+   * @param {object} fallback - Fallback variant if flag is not available
+   * @returns {object} The flag variant with key and value properties
+   */
+  getVariantSync(featureName, fallback) {
+    if (!this.areFlagsReady()) {
+      return fallback;
+    }
+
+    if (this.isNativeMode) {
+      return this.mixpanelImpl.getVariantSync(this.token, featureName, fallback);
+    } else if (this.jsFlags) {
+      return this.jsFlags.getVariantSync(featureName, fallback);
+    }
+    return fallback;
+  }
+
+  /**
+   * Get a feature flag variant value synchronously. Only works when flags are ready.
+   * @param {string} featureName - Name of the feature flag
+   * @param {any} fallbackValue - Fallback value if flag is not available
+   * @returns {any} The flag value
+   */
+  getVariantValueSync(featureName, fallbackValue) {
+    if (!this.areFlagsReady()) {
+      return fallbackValue;
+    }
+
+    if (this.isNativeMode) {
+      // Android returns a wrapped object due to React Native limitations
+      const result = this.mixpanelImpl.getVariantValueSync(this.token, featureName, fallbackValue);
+      if (result && typeof result === 'object' && 'type' in result) {
+        // Android wraps the response
+        return result.type === 'fallback' ? fallbackValue : result.value;
+      }
+      // iOS returns the value directly
+      return result;
+    } else if (this.jsFlags) {
+      return this.jsFlags.getVariantValueSync(featureName, fallbackValue);
+    }
+    return fallbackValue;
+  }
+
+  /**
+   * Check if a feature flag is enabled synchronously. Only works when flags are ready.
+   * @param {string} featureName - Name of the feature flag
+   * @param {boolean} fallbackValue - Fallback value if flag is not available
+   * @returns {boolean} True if enabled, false otherwise
+   */
+  isEnabledSync(featureName, fallbackValue = false) {
+    if (!this.areFlagsReady()) {
+      return fallbackValue;
+    }
+
+    if (this.isNativeMode) {
+      return this.mixpanelImpl.isEnabledSync(this.token, featureName, fallbackValue);
+    } else if (this.jsFlags) {
+      return this.jsFlags.isEnabledSync(featureName, fallbackValue);
+    }
+    return fallbackValue;
+  }
+
+  /**
+   * Get a feature flag variant asynchronously.
+   * Supports both callback and Promise patterns.
+   * @param {string} featureName - Name of the feature flag
+   * @param {object} fallback - Fallback variant if flag is not available
+   * @param {function} callback - Optional callback function
+   * @returns {Promise|void} Promise if no callback provided, void otherwise
+   */
+  getVariant(featureName, fallback, callback) {
+    // If callback provided, use callback pattern
+    if (typeof callback === 'function') {
+      if (this.isNativeMode) {
+        this.mixpanelImpl.getVariant(this.token, featureName, fallback)
+          .then(result => callback(result))
+          .catch(() => callback(fallback));
+      } else if (this.jsFlags) {
+        this.jsFlags.getVariant(featureName, fallback)
+          .then(result => callback(result))
+          .catch(() => callback(fallback));
+      } else {
+        callback(fallback);
+      }
+      return;
+    }
+
+    // Promise pattern
+    return new Promise((resolve) => {
+      if (this.isNativeMode) {
+        this.mixpanelImpl.getVariant(this.token, featureName, fallback)
+          .then(resolve)
+          .catch(() => resolve(fallback));
+      } else if (this.jsFlags) {
+        this.jsFlags.getVariant(featureName, fallback)
+          .then(resolve)
+          .catch(() => resolve(fallback));
+      } else {
+        resolve(fallback);
+      }
+    });
+  }
+
+  /**
+   * Get a feature flag variant value asynchronously.
+   * Supports both callback and Promise patterns.
+   * @param {string} featureName - Name of the feature flag
+   * @param {any} fallbackValue - Fallback value if flag is not available
+   * @param {function} callback - Optional callback function
+   * @returns {Promise|void} Promise if no callback provided, void otherwise
+   */
+  getVariantValue(featureName, fallbackValue, callback) {
+    // If callback provided, use callback pattern
+    if (typeof callback === 'function') {
+      if (this.isNativeMode) {
+        this.mixpanelImpl.getVariantValue(this.token, featureName, fallbackValue)
+          .then(result => callback(result))
+          .catch(() => callback(fallbackValue));
+      } else if (this.jsFlags) {
+        this.jsFlags.getVariantValue(featureName, fallbackValue)
+          .then(result => callback(result))
+          .catch(() => callback(fallbackValue));
+      } else {
+        callback(fallbackValue);
+      }
+      return;
+    }
+
+    // Promise pattern
+    return new Promise((resolve) => {
+      if (this.isNativeMode) {
+        this.mixpanelImpl.getVariantValue(this.token, featureName, fallbackValue)
+          .then(resolve)
+          .catch(() => resolve(fallbackValue));
+      } else if (this.jsFlags) {
+        this.jsFlags.getVariantValue(featureName, fallbackValue)
+          .then(resolve)
+          .catch(() => resolve(fallbackValue));
+      } else {
+        resolve(fallbackValue);
+      }
+    });
+  }
+
+  /**
+   * Check if a feature flag is enabled asynchronously.
+   * Supports both callback and Promise patterns.
+   * @param {string} featureName - Name of the feature flag
+   * @param {boolean} fallbackValue - Fallback value if flag is not available
+   * @param {function} callback - Optional callback function
+   * @returns {Promise|void} Promise if no callback provided, void otherwise
+   */
+  isEnabled(featureName, fallbackValue = false, callback) {
+    // If callback provided, use callback pattern
+    if (typeof callback === 'function') {
+      if (this.isNativeMode) {
+        this.mixpanelImpl.isEnabled(this.token, featureName, fallbackValue)
+          .then(result => callback(result))
+          .catch(() => callback(fallbackValue));
+      } else if (this.jsFlags) {
+        this.jsFlags.isEnabled(featureName, fallbackValue)
+          .then(result => callback(result))
+          .catch(() => callback(fallbackValue));
+      } else {
+        callback(fallbackValue);
+      }
+      return;
+    }
+
+    // Promise pattern
+    return new Promise((resolve) => {
+      if (this.isNativeMode) {
+        this.mixpanelImpl.isEnabled(this.token, featureName, fallbackValue)
+          .then(resolve)
+          .catch(() => resolve(fallbackValue));
+      } else if (this.jsFlags) {
+        this.jsFlags.isEnabled(featureName, fallbackValue)
+          .then(resolve)
+          .catch(() => resolve(fallbackValue));
+      } else {
+        resolve(fallbackValue);
+      }
+    });
+  }
+
+  /**
+   * Update the feature flags context for runtime targeting.
+   * This will trigger a reload of flags with the new context.
+   * @param {object} context - New context object with custom properties
+   */
+  async updateContext(context) {
+    if (this.isNativeMode) {
+      // For native mode, we need to reload flags with new context
+      // This would require native implementation support
+      return await this.mixpanelImpl.updateFlagsContext(this.token, context);
+    } else if (this.jsFlags) {
+      return await this.jsFlags.updateContext(context);
+    }
+    throw new Error("Feature flags are not initialized");
+  }
+}
\ No newline at end of file
diff --git a/javascript/mixpanel-main.js b/javascript/mixpanel-main.js
index 21c964f2..4a2cd269 100644
--- a/javascript/mixpanel-main.js
+++ b/javascript/mixpanel-main.js
@@ -21,10 +21,17 @@ export default class MixpanelMain {
     trackAutomaticEvents = false,
     optOutTrackingDefault = false,
     superProperties = null,
-    serverURL = "https://api.mixpanel.com"
+    serverURL = "https://api.mixpanel.com",
+    useGzipCompression = false,
+    featureFlagsOptions = {}
   ) {
     MixpanelLogger.log(token, `Initializing Mixpanel`);
 
+    // Store feature flags options for later use
+    this.featureFlagsOptions = featureFlagsOptions;
+    this.featureFlagsEnabled = featureFlagsOptions.enabled || false;
+    this.featureFlagsContext = featureFlagsOptions.context || {};
+
     await this.mixpanelPersistent.initializationCompletePromise(token);
     if (optOutTrackingDefault) {
       await this.optOutTracking(token);
@@ -37,6 +44,11 @@ export default class MixpanelMain {
     await this.registerSuperProperties(token, {
       ...superProperties,
     });
+
+    // Initialize feature flags if enabled
+    if (this.featureFlagsEnabled) {
+      MixpanelLogger.log(token, "Feature flags enabled during initialization");
+    }
   }
 
   getMetaData() {
diff --git a/package-lock.json b/package-lock.json
index bd7a668b..b3f9552f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mixpanel-react-native",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mixpanel-react-native",
-      "version": "3.1.1",
+      "version": "3.1.2",
       "license": "Apache-2.0",
       "dependencies": {
         "@react-native-async-storage/async-storage": "^1.21.0",