React

@vibe-flags/core ships a dedicated React integration under @vibe-flags/core/react.

Installation

npm install @vibe-flags/core

React 18 or 19 is required as a peer dependency.

Quick start

import { VibeFlagsToolbar, VibeFlagsBoolean } from "@vibe-flags/core/react";

function App() {
  return (
    <>
      <main>
        <VibeFlagsBoolean name="showBanner" description="Show welcome banner" default={true}>
          <div className="banner">Welcome to the beta!</div>
        </VibeFlagsBoolean>
      </main>
      <VibeFlagsToolbar />
    </>
  );
}

VibeFlagsToolbar renders the floating flag control panel. VibeFlagsBoolean self-registers the flag and shows its children only when the flag is truthy.

Advanced usage

vibeFlagsStore.register()

Register flags imperatively — useful at app startup before any component mounts:

import { vibeFlagsStore } from "@vibe-flags/core";

// Register a boolean flag
vibeFlagsStore.register({ key: "darkMode", type: "boolean", default: false });

// Register a select flag
vibeFlagsStore.register({
  key: "theme",
  type: "select",
  options: ["light", "dark", "auto"],
  default: "light",
});

useVibeFlags()

Subscribe to a flag value inside any component. The component re-renders automatically when the flag changes.

import { useVibeFlags } from "@vibe-flags/core/react";
import { vibeFlagsStore } from "@vibe-flags/core";

vibeFlagsStore.register({ key: "darkMode", type: "boolean", default: false });

function App() {
  const darkMode = useVibeFlags("darkMode");

  return (
    <div style={{ background: darkMode ? "#1a1a1a" : "#fff" }}>
      Dark mode is {darkMode ? "on" : "off"}
    </div>
  );
}

You can also pass a config object directly — the flag is registered on mount:

function ThemePicker() {
  const theme = useVibeFlags({
    key: "theme",
    type: "select",
    options: ["light", "dark", "auto"],
    default: "light",
  });

  return <p>Current theme: {theme}</p>;
}

References

useVibeFlags

// Subscribe to an already-registered flag by key
useVibeFlags(key: string): VibeFlagsValue | undefined

// Register a flag from config and subscribe
useVibeFlags(config: VibeFlagsConfig): VibeFlagsValue

Examples:

// Subscribe by key (flag must be registered elsewhere)
const enabled = useVibeFlags("featureX");

// Register a boolean flag inline
const darkMode = useVibeFlags({ key: "darkMode", type: "boolean", default: false });

// Register a select flag inline
const theme = useVibeFlags({
  key: "theme",
  type: "select",
  options: ["light", "dark"],
  default: "light",
});

---

vibeFlagsStore.register

vibeFlagsStore.register(config: VibeFlagsConfig): void

Where VibeFlagsConfig is one of:

// Boolean flag
{ key: string; type: 'boolean'; label?: string; default?: boolean }

// Select flag
{ key: string; type: 'select'; options: string[]; label?: string; default?: string }

Examples:

// Boolean
vibeFlagsStore.register({ key: "darkMode", type: "boolean", default: false });

// Select
vibeFlagsStore.register({
  key: "theme",
  type: "select",
  options: ["light", "dark", "auto"],
  default: "light",
});

---

VibeFlagsBoolean

React wrapper for <vibe-flags-boolean>. Self-registers the flag and renders children when the flag value matches value. If value is omitted, children are shown whenever the flag is truthy.

Prop	Type	Default	Description
name	string	required	Unique flag key
description	string	""	Label shown in toolbar
value	string	""	Expected value to show children
default	boolean	false	Initial value

import { VibeFlagsBoolean } from "@vibe-flags/core/react";

<VibeFlagsBoolean name="darkMode" description="Dark Mode" default={false}>
  <style>{`body { background: #1a1a1a; color: #fff; }`}</style>
</VibeFlagsBoolean>;

---

VibeFlagsSelect and VibeFlagsOption

React wrappers for <vibe-flags-select> and <vibe-flags-option>. Only the active option's children are rendered.

VibeFlagsSelect props:

Prop	Type	Default	Description
name	string	required	Unique flag key
description	string	""	Label shown in toolbar
default	string	first option	Default selection

VibeFlagsOption props:

Prop	Type	Description
value	string	Option identifier — children shown when this is active

import { VibeFlagsSelect, VibeFlagsOption } from "@vibe-flags/core/react";

<VibeFlagsSelect name="theme" description="Color theme" default="light">
  <VibeFlagsOption value="light">
    <style>{`:root { --bg: #fff; --text: #111; }`}</style>
  </VibeFlagsOption>
  <VibeFlagsOption value="dark">
    <style>{`:root { --bg: #111; --text: #fff; }`}</style>
  </VibeFlagsOption>
</VibeFlagsSelect>;