React SDK

The RuntimeHQ React SDK provides a context provider and hooks to easily consume the effective runtime state in your components.

This SDK is a pure state management SDK with:

No visual UI components (Customers use their own design systems).
No CSS, Tailwind, or style sheet dependencies.
No external state libraries.

Installation

npm install @theruntimehq/react @theruntimehq/js

Validate After Installation

After installing and setting up the SDK, validate your integration using Non-Production Simulation. Simulation allows you to safely test state changes, UI fallbacks, and capability degradation during peacetime using your non-production key (rt_test_...) without impacting production traffic.

Setup

You will need to provide a runtimeKey for your application. See the Runtime Keys documentation for details on where to find your key and how environments are separated.

Wrap your application in the RuntimeHQProvider:

import { RuntimeHQProvider } from "@theruntimehq/react";

export default function Root() {
  return (
    <RuntimeHQProvider runtimeKey="rt_prod_your_key_here">
      <App />
    </RuntimeHQProvider>
  );
}

Provider Props

Prop	Type	Required	Default	Description
`runtimeKey`	`string`	Yes	-	Your RuntimeHQ API status key (must start with `rt_prod_` or `rt_test_`). This is a public, read-only key that is absolutely safe for client-side exposure or browser environments.
`intervalSeconds`	`number`	No	`60`	Configurable polling interval for updates in seconds. Defaults to 60 seconds.

Usage

1. Capability Hook (`useCapability`)

The useCapability hook is the recommended, idiomatic way to monitor feature health in components. It encapsulates the fail-open pattern—if RuntimeHQ is loading, encounters a network issue, or the capability is unconfigured, it safely defaults to isOperational: true and isOutage: false, ensuring normal component functionality is not disrupted by control plane or network issues.

Beyond binary toggling during outages, capability health enables adaptive client behaviors—such as dynamically backing off input debounce delays when a capability is degraded to reduce pressure on backend services.

import { useCapability } from "@theruntimehq/react";

function SearchComponent() {
  const { isOutage, isDegraded, message } = useCapability("search");

  // Dynamically back off request frequency when search capability is degraded
  const debounceDelayMs = isDegraded ? 1200 : 300;
  
  return (
    <div className="search-container">
      <input 
        type="text" 
        placeholder="Search products..." 
        disabled={isOutage}
        onChange={debounce(handleSearch, debounceDelayMs)}
      />
      {(isOutage || isDegraded) && message && (
        <p className={`helper-message ${isOutage ? 'text-red-600' : 'text-amber-600'}`}>
          {message}
        </p>
      )}
    </div>
  );
}

`useCapability` Return Value

interface UseCapabilityResult {
  capability: CapabilityState | undefined; // Raw capability state object (or undefined if not present)
  state: RuntimeState;                     // Current state, defaults to "OPERATIONAL" (fail-open)
  message: string;                         // Operational or degraded message (defaults to "")
  isOperational: boolean;                  // true by default (fail-open)
  isDegraded: boolean;                     // true if state === "DEGRADED"
  isOutage: boolean;                       // true if state === "OUTAGE"
  isMaintenance: boolean;                  // true if state === "MAINTENANCE"
  exists: boolean;                         // true if capability is registered in configuration
  loading: boolean;                        // true until the first fetch completes
  error: Error | null;                     // Captured network or validation error (if any)
}

2. Context Hook (`useRuntimeHQ`)

For application-wide status banners, multi-capability dashboards, or lower-level inspection, consume the global context directly with useRuntimeHQ():

import { useRuntimeHQ, isOperational } from "@theruntimehq/react";

function StatusBanner() {
  const { runtime, loading, error } = useRuntimeHQ();

  if (loading || !runtime || isOperational(runtime)) return null;

  return (
    <div className={`banner ${runtime.state.toLowerCase()}`}>
      ⚠️ {runtime.message}
    </div>
  );
}

`useRuntimeHQ` Return Value

interface RuntimeHQContextValue {
  runtime: RuntimeResponse | null;                                   // Detailed status info or null before first fetch
  loading: boolean;                                                  // true until the first fetch (success or failure) completes
  error: Error | null;                                               // Captured network or validation error (if any)
  hasCapability: (name: string) => boolean;                          // Checks if a capability is registered
  getCapabilityState: (name: string) => CapabilityState | undefined; // Returns resolved capability state
}

Important

Both useCapability and useRuntimeHQ must be used within a <RuntimeHQProvider>, or they will throw a descriptive error.

For comprehensive recipes, see the React Examples & Patterns guide or browse the examples directory on GitHub.

Validating the Integration

After installing the SDK and setting up your provider, validate that your application responds as expected to operational state changes. Do not wait for a live incident to test client fallback behavior.

Use Non-Production Simulation to verify your integration during peacetime:

Use a Non-Production Key: Configure your development or staging environment with your application's non-production runtime key (rt_test_...). See Runtime Keys for key management.
Trigger a Simulation: In the RuntimeHQ Console, navigate to your application details and locate the Non-Production Simulation State panel. Select a simulated state (DEGRADED, OUTAGE, or MAINTENANCE), choose affected capabilities (such as search), and optionally attach an operational message.
Verify Component Behavior: Confirm that your React components react appropriately to the simulated state (e.g., displaying fallback messages, disabling search inputs, or hiding degraded features).
Reset Simulation: Clear the simulation in the Console to return your non-production environment to its baseline operational state.

Convenience Helpers

Quickly determine states using utility checkers. These accept either the full RuntimeResponse object, a CapabilityState object, the RuntimeState string, or null/undefined.

import { 
  isOperational, 
  isMaintenance, 
  isDegraded, 
  isOutage 
} from "@theruntimehq/react";

// Usage
isOperational(runtime)  // returns boolean
isMaintenance(runtime)  // returns boolean
isDegraded(runtime)     // returns boolean
isOutage(runtime)       // returns boolean

Links & Resources:

React SDK

On this page