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

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

Component Example

Consume dynamic state changes reactively within your components. The useRuntimeHQ hook automatically listens to state changes managed by the provider.

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

function SearchComponent() {
  const { loading, error, getCapabilityState } = useRuntimeHQ();

  if (loading || error) return null;

  const searchCapability = getCapabilityState('search');
  const isSearchDown = searchCapability?.state === "OUTAGE";
  const isSearchDegraded = searchCapability?.state === "DEGRADED";
  
  return (
    <div className="search-container">
      <input 
        type="text" 
        placeholder="Search products..." 
        disabled={isSearchDown}
      />
      {(isSearchDown || isSearchDegraded) && (
        <p className={`helper-message ${isSearchDown ? 'text-red-600' : 'text-amber-600'}`}>
          {searchCapability.message}
        </p>
      )}
    </div>
  );
}

For more advanced use cases, check out the examples directory on GitHub.

Hook 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)
}

Important

If useRuntimeHQ is invoked outside a <RuntimeHQProvider>, it throws a descriptive error: useRuntimeHQ must be used within a RuntimeHQProvider

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