Complete reference for hooks, provider props, return values, and helpers in @theruntimehq/react

React API Reference

The @theruntimehq/react package exports the following provider, hooks, helper functions, and TypeScript types.

`<RuntimeHQProvider>`

The root provider component that manages background state synchronization for your application. It maintains an active polling lifecycle with the RuntimeHQ edge network and shares the runtime state with all descendant components via React Context.

Props

Prop	Type	Required	Default	Description
`runtimeKey`	`string`	Yes	—	The Runtime Key (`rt_prod_...` or `rt_test_...`) for your application. Safe for client-side and browser usage.
`intervalSeconds`	`number`	No	`60`	Background polling interval in seconds.

Usage

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

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

Hooks

`useRuntimeHQ`

Accesses the global application-level runtime status from the nearest <RuntimeHQProvider>.

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

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

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

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

Return Value (`RuntimeHQContextValue`)

interface RuntimeHQContextValue {
  runtime: RuntimeResponse | null;
  loading: boolean;
  error: Error | null;
  hasCapability: (name: string) => boolean;
  getCapabilityState: (name: string) => CapabilityState | undefined;
}

Property	Type	Description
`runtime`	`RuntimeResponse \| null`	The full runtime response object containing current application state, message, and capabilities. `null` before initial fetch completes.
`loading`	`boolean`	`true` during the initial fetch; `false` once resolved.
`error`	`Error \| null`	Error object if initialization or the initial fetch fails, otherwise `null`.
`hasCapability`	`(name: string) => boolean`	Checks whether a capability is registered on this application.
`getCapabilityState`	`(name: string) => CapabilityState \| undefined`	Returns the raw `CapabilityState` object for a capability by name.

`useCapability`

The recommended, idiomatic hook to monitor feature health, gate workflows, and implement adaptive client behaviors.

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="search" 
        placeholder="Search products..." 
        disabled={isOutage}
        onChange={debounce(handleSearch, debounceDelayMs)}
      />
      {(isOutage || isDegraded) && message && (
        <p className="helper-text">{message}</p>
      )}
    </div>
  );
}

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	The unique capability identifier configured in RuntimeHQ (e.g., `"search"`, `"payments"`).

Return Value (`UseCapabilityResult`)

interface UseCapabilityResult {
  capability: CapabilityState | undefined;
  state: RuntimeState;
  message: string;
  isOperational: boolean;
  isDegraded: boolean;
  isOutage: boolean;
  isMaintenance: boolean;
  exists: boolean;
  loading: boolean;
  error: Error | null;
}

Property	Type	Default (Fail-Open)	Description
`isOperational`	`boolean`	`true`	`true` when capability is OPERATIONAL or during initial load / network errors.
`isDegraded`	`boolean`	`false`	`true` when capability state is DEGRADED.
`isOutage`	`boolean`	`false`	`true` when capability state is OUTAGE.
`isMaintenance`	`boolean`	`false`	`true` when capability state is MAINTENANCE.
`state`	`RuntimeState`	`"OPERATIONAL"`	The resolved runtime state string (`"OPERATIONAL"`, `"DEGRADED"`, `"OUTAGE"`, or `"MAINTENANCE"`).
`message`	`string`	`""`	User-facing status or degradation message from RuntimeHQ.
`exists`	`boolean`	`false`	`true` if the capability is registered in configuration.
`capability`	`CapabilityState \| undefined`	`undefined`	The raw capability state object.
`loading`	`boolean`	`true`	`true` until the initial status check completes.
`error`	`Error \| null`	`null`	Captured network or validation error (if any).

Fail-Open Behavior

useCapability is designed with fail-open defaults. If network connectivity to RuntimeHQ is interrupted, isOperational remains true and isOutage remains false, preventing control-plane incidents from breaking your application.

Provider Required

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

`useRuntimeHQState`

A standalone hook to fetch and watch RuntimeHQ status directly without requiring a context provider. Ideal for isolated micro-frontends, embedded widgets, or standalone scripts.

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

function StandaloneWidget() {
  const { runtime, loading, error } = useRuntimeHQState({
    runtimeKey: "rt_prod_your_key_here",
    intervalSeconds: 60,
  });

  if (loading || !runtime) return null;
  return <div>Status: {runtime.state}</div>;
}

Options (`UseRuntimeHQStateOptions`)

Option	Type	Required	Default	Description
`runtimeKey`	`string`	Yes	—	RuntimeHQ status key.
`intervalSeconds`	`number`	No	`60`	Background polling interval in seconds. Defaults to 60 seconds.

Convenience Helpers

Utility checkers to quickly evaluate states on RuntimeResponse objects, CapabilityState objects, or raw state strings.

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

Signatures

Each helper accepts RuntimeResponse | CapabilityState | RuntimeState | null | undefined and returns a boolean:

Helper	Evaluates to `true` when
`isOperational(input)`	State is `"OPERATIONAL"`. Returns `false` if input is `null` or undefined.
`isMaintenance(input)`	State is `"MAINTENANCE"`.
`isDegraded(input)`	State is `"DEGRADED"`.
`isOutage(input)`	State is `"OUTAGE"`.

Example

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

export function SystemNotice() {
  const { runtime } = useRuntimeHQ();

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

  if (isMaintenance(runtime)) {
    return <div className="notice-maintenance">Scheduled Maintenance: {runtime.message}</div>;
  }

  return <div className="notice-outage">Attention: {runtime.message}</div>;
}

TypeScript Types

All core TypeScript types can be imported directly from @theruntimehq/react:

import type {
  RuntimeState,
  CapabilityState,
  RuntimeResponse,
  RuntimeHQProviderProps,
  RuntimeHQContextValue,
  UseCapabilityResult,
  UseRuntimeHQStateOptions,
} from "@theruntimehq/react";

`RuntimeState`

type RuntimeState = "OPERATIONAL" | "MAINTENANCE" | "DEGRADED" | "OUTAGE";

`CapabilityState`

interface CapabilityState {
  capabilityName: string;
  state: RuntimeState;
  message: string;
}

`RuntimeResponse`

interface RuntimeResponse {
  applicationId: string;
  state: RuntimeState;
  message: string;
  capabilityStates: CapabilityState[];
  version: number;
  updatedAt: Date;
  dataStatus: "FRESH" | "STALE";
  lastSuccessfulFetchAt: Date;

  hasCapability(name: string): boolean;
  getCapabilityState(name: string): CapabilityState | undefined;
}

React API Reference

On this page