The Hyphen React SDK provides React components, hooks, and higher-order components (HOCs) for integrating Hyphen's feature flag and toggle service into your React applications.
npm install @hyphen/react-sdkThe SDK provides three ways to integrate Hyphen into your React application:
Wrap your root component with withToggleProvider():
import{withToggleProvider}from'@hyphen/react-sdk';importAppfrom'./App';exportdefaultwithToggleProvider({publicApiKey: 'public_...',applicationId: 'my-app',environment: 'production',defaultContext: {user: {id: 'user-123',email: 'user@example.com'}}})(App);Use the ToggleProvider component directly:
import{ToggleProvider}from'@hyphen/react-sdk';importAppfrom'./App';functionRoot(){return(<ToggleProviderpublicApiKey="public_..."applicationId="my-app"environment="production"defaultContext={{user: {id: 'user-123',email: 'user@example.com'}}}><App/></ToggleProvider>);}Access feature flags in any component:
import{useToggle}from'@hyphen/react-sdk';functionMyComponent(){consttoggle=useToggle();// Get boolean feature flagconstisNewFeatureEnabled=toggle.getBoolean('new-feature',false);// Get string feature flagconsttheme=toggle.getString('theme','light');// Get number feature flagconstmaxItems=toggle.getNumber('max-items',10);// Get object feature flagconstconfig=toggle.getObject('ui-config',{layout: 'grid'});return(<div>{isNewFeatureEnabled&&<NewFeature/>}<p>Theme: {theme}</p><p>Max Items: {maxItems}</p></div>);}All configuration options are passed to the Toggle instance from @hyphen/browser-sdk:
| Option | Type | Required | Description |
|---|---|---|---|
publicApiKey | string | Yes | Your Hyphen public API key (starts with public_) |
applicationId | string | No | Application identifier |
environment | string | No | Environment name (e.g., 'development', 'production') |
defaultContext | object | No | Default evaluation context (user, targeting, etc.) |
horizonUrls | string[] | No | Custom Horizon endpoint URLs for load balancing |
defaultTargetKey | string | No | Default targeting key |
The defaultContext option allows you to set default user and targeting information:
{defaultContext: {targetingKey: 'user-123',user: {id: 'user-123',email: 'user@example.com',name: 'John Doe',customAttributes: {plan: 'premium',region: 'us-west'}},ipAddress: '192.168.1.1',customAttributes: {deviceType: 'mobile'}}}React context provider component that creates and provides a Toggle instance.
Props: Extends ToggleOptions from @hyphen/browser-sdk plus:
children: ReactNode - Components to wrap with the provider
Higher-order component that wraps a component with ToggleProvider.
Parameters:
options:ToggleOptions- Configuration for the Toggle instance
Returns: Function that accepts a component and returns a wrapped component
React hook to access the Toggle instance from context.
Returns:Toggle instance from @hyphen/browser-sdk
Throws: Error if used outside of ToggleProvider
The Toggle instance provides these methods:
getBoolean(key, defaultValue, options?)- Get a boolean feature flaggetString(key, defaultValue, options?)- Get a string feature flaggetNumber(key, defaultValue, options?)- Get a number feature flaggetObject<T>(key, defaultValue, options?)- Get an object feature flagget<T>(key, defaultValue, options?)- Generic getter for any type
All methods accept an optional options parameter for context overrides:
constisEnabled=toggle.getBoolean('feature-key',false,{context: {user: {id: 'different-user'}}});The SDK is written in TypeScript and provides full type definitions out of the box.
importtype{ToggleProviderProps}from'@hyphen/react-sdk';constconfig: ToggleProviderProps={publicApiKey: 'public_...',applicationId: 'my-app',children: <App/>};functionFeatureFlag({ flagKey, children }){consttoggle=useToggle();constisEnabled=toggle.getBoolean(flagKey,false);returnisEnabled ? <>{children}</> : null;}// Usage<FeatureFlagflagKey="new-dashboard"><NewDashboard/></FeatureFlag>functionABTest(){consttoggle=useToggle();constvariant=toggle.getString('homepage-variant','control');switch(variant){case'variant-a':
return<HomepageVariantA/>;case'variant-b':
return<HomepageVariantB/>;default:
return<HomepageControl/>;}}functionConfigurableComponent(){consttoggle=useToggle();constconfig=toggle.getObject('component-config',{maxItems: 10,showImages: true,layout: 'grid'});return(<ComponentmaxItems={config.maxItems}showImages={config.showImages}layout={config.layout}/>);}We welcome contributions to the Hyphen Node.js SDK! If you have an idea for a new feature, bug fix, or improvement, please follow the Contribution guidelines and our Code of Conduct.
This project is licensed under the MIT License. See the LICENSE file for details. The copyright for this project is held by Hyphen, Inc. All rights reserved.