How to Use openstatus React Widget

Install the npm package:

npm install @openstatus/react

React server component

import { StatusWidget } from "@openstatus/react";

export function Page() {
  return <StatusWidget slug="status" />;
}

It will automatically attach the slug to the href to allow the user to open a new tab on click to https://slug.openstatus.dev. If you want to redirect to a specific page, use the href property:

<StatusWidget slug="documenso" href="https://status.documenso.com" />

Styling

With Tailwind CSS

The widget is styled with Tailwind utility classes, so Tailwind has to scan the published package for them.

Tailwind v4 — add a @source directive to the CSS file that imports Tailwind:

/* app/globals.css */
@import "tailwindcss";
@source "../node_modules/@openstatus/react/dist";

Tailwind v3 — add the package to content:

// tailwind.config.js
module.exports = {
  content: [
    "./app/**/*.{tsx,ts,mdx,md}",
    "./node_modules/@openstatus/react/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Without Tailwind CSS

// app/layout.tsx
import "@openstatus/react/dist/styles.css";

Typed fetch function

import { getStatus } from "@openstatus/react";

// React Server Component
async function CustomStatusWidget() {
  const res = await getStatus("slug");
  // ^StatusResponse = { status: Status }

  const { status } = res;
  // ^Status = "unknown" | "operational" | "degraded_performance" | "partial_outage" | "major_outage" | "under_maintenance" | "incident"

  return <div>{/* customize */}</div>;
}

getStatus never throws: a network failure or a non-2xx response degrades to { status: "unknown" } rather than bubbling an error into your page.

Pointing at a self-hosted API

Both getStatus and StatusWidget call https://api.openstatus.dev by default. If you self-host openstatus, set OPENSTATUS_API_URL on the server — that is the only lever for StatusWidget, which takes just slug and href. getStatus additionally accepts the base URL as a second argument:

const res = await getStatus("slug", "https://api.status.example.com");

The variable is read at request time and has no NEXT_PUBLIC_ prefix, so a prebuilt image can be pointed at a different API without rebuilding.