# React SDK

> @switchbox/react — provider, hooks, and the Feature component.

`@switchbox/react` adds React hooks and a component on top of
[`switchbox-js`](/docs/sdk/javascript). It contains no evaluation or networking
logic of its own — just React primitives that re-render when a flag changes.

```bash
npm install switchbox-js @switchbox/react
```

`switchbox-js` is a peer dependency — you create the client with it and hand it to
the provider. The same reference ships in the [README on
npm](https://www.npmjs.com/package/@switchbox/react).

## SwitchboxProvider

Wrap your app once, near the root, with a client you created via the core SDK:

```tsx
import { Switchbox } from 'switchbox-js';
import { SwitchboxProvider } from '@switchbox/react';

const client = await Switchbox.create({ sdkKey: 'your-sdk-key' });

function Root() {
  return (
    <SwitchboxProvider client={client}>
      <App />
    </SwitchboxProvider>
  );
}
```

| Prop | Type | Description |
|---|---|---|
| `client` | `Switchbox` | A client from `switchbox-js`. |

The provider subscribes to the client's config changes, so every hook below
re-renders when a new config arrives (within one poll interval of a dashboard
change).

## useFlag(key, user?)

```tsx
import { useFlag } from '@switchbox/react';

function Checkout() {
  const showNew = useFlag('new_checkout', { user_id: '42' });
  return showNew ? <NewCheckout /> : <OldCheckout />;
}
```

Returns the current boolean for a flag and re-renders the component when it
changes. Returns `false` until the first config loads or if the flag is absent.

## useValue(key, user?, default?)

```tsx
import { useValue } from '@switchbox/react';

function ThemedPage() {
  const theme = useValue('theme', { user_id: '42' }, 'light');
  return <div className={theme}>…</div>;
}
```

Returns the resolved value of a string, number, or JSON flag (a `json` flag comes
back as a parsed object/array), falling back to `default`.

## useClient()

```tsx
import { useClient } from '@switchbox/react';

function Advanced() {
  const client = useClient();
  // the underlying switchbox-js client, for getAllFlags(), destroy(), etc.
}
```

Returns the `switchbox-js` client from context, for cases the hooks don't cover.

## Feature

A declarative wrapper — render `children` when the flag is on, `fallback`
otherwise:

```tsx
import { Feature } from '@switchbox/react';

function Dashboard() {
  return (
    <Feature flag="new_dashboard" user={{ user_id: '42' }} fallback={<OldDashboard />}>
      <NewDashboard />
    </Feature>
  );
}
```

| Prop | Type | Description |
|---|---|---|
| `flag` | `string` | The flag key. |
| `user` | `UserContext` | Optional user context for targeting/rollouts. |
| `fallback` | `ReactNode` | Rendered when the flag is off. Optional. |
| `children` | `ReactNode` | Rendered when the flag is on. |

## Next

- [JavaScript SDK](/docs/sdk/javascript) — the client these hooks wrap.
- [React quickstart](/docs/quickstart/react) — the three-step setup.
- [Use with OpenFeature](/docs/sdk/openfeature): prefer the vendor-neutral API? Same hooks idea, zero lock-in.