Gradual feature flag SDK for React
npm install @gradual-so/sdk-reactReact SDK for Gradual feature flags. Provides a provider and hooks for evaluating flags in React components.
``bash`
npm install @gradual-so/sdk-react @gradual-so/sdk
Wrap your app with the provider:
`tsx
import { GradualProvider } from '@gradual-so/sdk-react'
function App() {
return (
)
}
`
Use flags in components:
`tsx
import { useFlag } from '@gradual-so/sdk-react'
function MyComponent() {
const showBanner = useFlag('show-banner', { fallback: false })
const theme = useFlag('theme', { fallback: 'light' })
return (
The return type is inferred from
fallback -- boolean for false, string for 'light', etc.User targeting
Use
useGradual to set user context. All flag evaluations will include this context:`tsx
import { useGradual } from '@gradual-so/sdk-react'
import { useEffect } from 'react'function AuthHandler({ user }) {
const { identify, reset } = useGradual()
useEffect(() => {
if (user) {
identify({ userId: user.id, plan: user.plan })
} else {
reset()
}
}, [user])
return null
}
`Override context for a single flag:
`tsx
const enabled = useFlag('feature', {
fallback: false,
context: { itemId: item.id },
})
`Loading states
By default,
useFlag returns the fallback value while the SDK initializes and the resolved value once ready. To distinguish between these states, use detail: true:`tsx
const { value, isLoading, isReady } = useFlag('experiment', {
fallback: 'control',
detail: true,
})if (isLoading) return
return
`API
$3
Initializes the Gradual SDK and provides it to child components.
| Prop | Type | Required | Description |
|---|---|---|---|
|
apiKey | string | Yes | Your Gradual API key |
| environment | string | Yes | Environment slug (e.g. production) |
| baseUrl | string | No | Custom API base URL |$3
Returns the flag value directly, or a detail object when
detail: true.`typescript
// Returns T (type inferred from fallback)
const value = useFlag('key', { fallback: defaultValue })// Returns { value: T, isLoading: boolean, isReady: boolean }
const detail = useFlag('key', { fallback: defaultValue, detail: true })
`| Option | Type | Required | Description |
|---|---|---|---|
|
fallback | T | Yes | Default value when flag is missing or SDK is loading |
| context | Record | No | Evaluation context override for this flag |
| detail | boolean | No | Return { value, isLoading, isReady } instead of just the value |$3
Returns methods for managing user context and SDK state.
`typescript
const { identify, reset, refresh, isReady } = useGradual()
`| Property | Type | Description |
|---|---|---|
|
identify | (context) => void | Set persistent user context for all evaluations |
| reset | () => void | Clear the identified user context |
| refresh | () => Promise | Fetch the latest flag snapshot from the server |
| isReady | boolean` | Whether the SDK has finished initializing |MIT