Hyphen SDK for React
npm install @hyphen/react-sdk




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.
``bash`
npm install @hyphen/react-sdk
The SDK provides three ways to integrate Hyphen into your React application:
Wrap your root component with withToggleProvider():
`tsx
import { withToggleProvider } from '@hyphen/react-sdk';
import App from './App';
export default withToggleProvider({
publicApiKey: 'public_...',
applicationId: 'my-app',
environment: 'production',
defaultContext: {
user: {
id: 'user-123',
email: 'user@example.com'
}
}
})(App);
`
Use the ToggleProvider component directly:
`tsx
import { ToggleProvider } from '@hyphen/react-sdk';
import App from './App';
function Root() {
return (
applicationId="my-app"
environment="production"
defaultContext={{
user: {
id: 'user-123',
email: 'user@example.com'
}
}}
>
);
}
`
Access feature flags in any component:
`tsx
import { useToggle } from '@hyphen/react-sdk';
function MyComponent() {
const toggle = useToggle();
// Get boolean feature flag
const isNewFeatureEnabled = toggle.getBoolean('new-feature', false);
// Get string feature flag
const theme = toggle.getString('theme', 'light');
// Get number feature flag
const maxItems = toggle.getNumber('max-items', 10);
// Get object feature flag
const config = toggle.getObject('ui-config', { layout: 'grid' });
return (
Theme: {theme}
Max Items: {maxItems}
Configuration Options
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 |$3
The
defaultContext option allows you to set default user and targeting information:`tsx
{
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'
}
}
}
`API Reference
$3
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$3
Higher-order component that wraps a component with
ToggleProvider.Parameters:
-
options: ToggleOptions - Configuration for the Toggle instanceReturns: Function that accepts a component and returns a wrapped component
$3
React hook to access the Toggle instance from context.
Returns:
Toggle instance from @hyphen/browser-sdkThrows: Error if used outside of
ToggleProvider$3
The
Toggle instance provides these methods:-
getBoolean(key, defaultValue, options?) - Get a boolean feature flag
- getString(key, defaultValue, options?) - Get a string feature flag
- getNumber(key, defaultValue, options?) - Get a number feature flag
- getObject - Get an object feature flag
- get - Generic getter for any typeAll methods accept an optional
options parameter for context overrides:`tsx
const isEnabled = toggle.getBoolean('feature-key', false, {
context: {
user: { id: 'different-user' }
}
});
`TypeScript Support
The SDK is written in TypeScript and provides full type definitions out of the box.
`tsx
import type { ToggleProviderProps } from '@hyphen/react-sdk';const config: ToggleProviderProps = {
publicApiKey: 'public_...',
applicationId: 'my-app',
children:
};
`Examples
$3
`tsx
function FeatureFlag({ flagKey, children }) {
const toggle = useToggle();
const isEnabled = toggle.getBoolean(flagKey, false); return isEnabled ? <>{children}> : null;
}
// Usage
`$3
`tsx
function ABTest() {
const toggle = useToggle();
const variant = toggle.getString('homepage-variant', 'control'); switch (variant) {
case 'variant-a':
return ;
case 'variant-b':
return ;
default:
return ;
}
}
`$3
`tsx
function ConfigurableComponent() {
const toggle = useToggle();
const config = toggle.getObject('component-config', {
maxItems: 10,
showImages: true,
layout: 'grid'
}); return (
maxItems={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.