useConfig

useConfig(key) returns one configuration value. The first render shows the cached value or the default. The hook then fetches the current value from the API and re-renders when it arrives. Configuration values are strings. Read Remote configuration.

import { useConfig } from '@grainql/analytics-web/react';

function Hero() {
  const { value } = useConfig('hero_text');

  return <h1>{value ?? 'Welcome'}</h1>;
}

Signature

function useConfig(key: string, options?: UseConfigOptions): UseConfigResult;

Options

Option	Type	Rule
`forceRefresh`	`boolean`	Optional. When `true`, the fetch skips the cache and reads from the API.
`immediateKeys`	`string[]`	Optional. The keys that the API returns at once. Default is `[key]`.
`properties`	`Record<string, string>`	Optional. Properties that the dashboard rules evaluate. Read Personalization.

Result

Field	Type	Meaning
`value`	`string \| undefined`	The value. `undefined` when the key has no cached, default, or fetched value.
`isRefreshing`	`boolean`	`true` while a fetch is in progress.
`error`	`Error \| null`	The error of the last fetch. `null` at the start of each fetch.
`refresh`	`() => Promise<void>`	Runs the fetch again with the same options.

Cache-first behavior

On the first render, the hook reads client.getConfig(key). The result comes from the cache or from defaultConfigurations. There is no loading state.
After mount, the hook calls client.fetchConfig with the options. When the response holds the key, value updates and the component re-renders.
The hook subscribes to the configuration change listener of the client. When any fetch or the refresh timer changes the key, value updates.
When the fetch fails, error holds the failure and value keeps the cached or default value.

The hook fetches again when key, forceRefresh, immediateKeys, or properties change.

Define properties and immediateKeys outside the component or memoize them with useMemo. The hook compares them by reference. An object literal in the render body is a new object on every render, so the hook fetches on every render.

Default values

Set defaultConfigurations on the provider. The first render shows the default, also when the device is offline.

<GrainProvider
  config={{
    tenantId: 'your-tenant-id',
    defaultConfigurations: { hero_text: 'Welcome' },
  }}
>
  <App />
</GrainProvider>

Feature flag

Values are strings. Compare with 'true'. Read Feature flags.

function App() {
  const { value: newUiEnabled } = useConfig('new_ui_enabled');

  return newUiEnabled === 'true' ? <NewUI /> : <LegacyUI />;
}

Personalized value

const configProperties = { plan: 'premium', location: 'US' };

function Hero() {
  const { value } = useConfig('hero_text', { properties: configProperties });

  return <h1>{value}</h1>;
}

Refresh and errors

function Hero() {
  const { value, isRefreshing, error, refresh } = useConfig('hero_text');

  return (
    <div>
      <h1>{value ?? 'Welcome'}</h1>
      {isRefreshing && <span>Updating</span>}
      {error && <span>Configuration fetch failed. The last known value is shown.</span>}
      <button onClick={refresh}>Refresh</button>
    </div>
  );
}

Several keys

Call useConfig one time per key. Each call re-renders only when its own key changes. For many keys, or to iterate over all keys, read useAllConfigs.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Signature

Options

Result

Cache-first behavior

Default values

Feature flag

Personalized value

Refresh and errors

Several keys

​Signature

​Options

​Result

​Cache-first behavior

​Default values

​Feature flag

​Personalized value

​Refresh and errors

​Several keys

Signature

Options

Result

Cache-first behavior

Default values

Feature flag

Personalized value

Refresh and errors

Several keys