# Vibe Flags — Full Documentation

> Offline-first feature flag toolkit that lives in your HTML. No servers. No config files. No build step. Made for agents and LLMs.

Vibe Flags is a set of web components for managing feature flags entirely in the browser. Add one CDN script tag, write HTML, and toggle features with a floating toolbar. State persists in localStorage.

---

## Getting Started

Add one script tag, write some HTML. That's it.

### Quick Start

```html
<script type="module" src="https://unpkg.com/@vibe-flags/core"></script>

<vibe-flags-boolean name="showBanner" description="Welcome banner" value="true">
  <div style="padding: 16px; background: #dbeafe; border-radius: 8px;">
    Welcome to the beta! This banner is controlled by a feature flag.
  </div>
</vibe-flags-boolean>

<vibe-flags-boolean name="darkMode" description="Dark mode" value="true">
  <style>body { background: #1a1a1a; color: #fafafa; }</style>
</vibe-flags-boolean>

<vibe-flags-toolbar></vibe-flags-toolbar>
```

A toggle button appears on the right edge of your page. Click it to open the toolbar, flip some flags, and watch the page react. Values persist across refreshes.

No JavaScript. No config objects. No build step.

### How It Works

1. Each flag component self-registers when it connects to the DOM
2. `<vibe-flags-toolbar>` discovers all registered flags and renders controls
3. Toggling a flag updates `localStorage` and re-evaluates every flag
4. Children stay hidden until JS confirms they should be visible — no flash of content

### URL Overrides

Override any flag via URL query parameter without persisting to localStorage:

```
https://yourapp.com?vf:darkMode=true&vf:theme=dark
```

- Format: `?vf:<flag-name>=<value>`
- URL params take priority over localStorage values
- URL params are ephemeral — not saved across page loads
- Boolean flags: accept `true` or `false` only; any other value is ignored
- Select flags: value must be a valid option; unrecognized values are ignored

### Installation

CDN (recommended):
```html
<script type="module" src="https://unpkg.com/@vibe-flags/core"></script>
```

npm:
```bash
npm install @vibe-flags/core
```

Then import in your code:
```ts
import '@vibe-flags/core';
```

---

## Flag Types

### Boolean Flags

`<vibe-flags-boolean>` is a simple on/off toggle. Starts as `false`.

```html
<vibe-flags-boolean name="darkMode" description="Dark mode" value="true">
  <div>Dark mode is active!</div>
</vibe-flags-boolean>
```

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `name` | Yes | — | Unique identifier for the flag |
| `description` | No | `""` | Label shown in the toolbar (falls back to `name`) |
| `value` | No | `""` | Expected value to show children. If omitted, children are always shown. |

#### Showing content for both states

Use two elements with `value="true"` and `value="false"`:

```html
<vibe-flags-boolean name="newNavbar" description="New Navbar" value="true">
  <NewNavbar />
</vibe-flags-boolean>

<vibe-flags-boolean name="newNavbar" value="false">
  <OldNavbar />
</vibe-flags-boolean>
```

### Select Flags

`<vibe-flags-select>` lets users pick from a list. Starts as the first option. Each choice is a `<vibe-flags-option>`.

```html
<vibe-flags-select name="theme" description="Theme variant">
  <vibe-flags-option value="light">
    <div>Light theme</div>
  </vibe-flags-option>
  <vibe-flags-option value="dark">
    <div>Dark theme</div>
  </vibe-flags-option>
  <vibe-flags-option value="auto">
    <div>Auto theme</div>
  </vibe-flags-option>
</vibe-flags-select>
```

| Attribute | Required | Default | Description |
|-----------|----------|---------|-------------|
| `name` | Yes | — | Unique identifier for the flag |
| `description` | No | `""` | Label shown in the toolbar (falls back to `name`) |

#### `<vibe-flags-option>`

| Attribute | Required | Description |
|-----------|----------|-------------|
| `value` | Yes | The option value. Children are shown only when this option is active. |

### URL Query Parameter Overrides

Override any flag's value via URL without touching localStorage:

```
https://yourapp.com?vf:dark-mode=true&vf:theme=dark
```

**Rules:**
- URL params take priority over localStorage values when present.
- URL params are **ephemeral** — not written to localStorage, do not persist across page loads.
- Boolean flags accept `true` or `false`; any other value is ignored and falls back to localStorage or default.
- Select flags accept any value in the options list; unrecognized values are ignored.

---

## API Reference — Components

### `<vibe-flags-boolean>`

Declares a boolean flag and conditionally renders its children. Self-registers with the store on connect. Starts as `false`.

#### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `string` | `''` | Unique flag identifier |
| `description` | `string` | `''` | Label shown in the toolbar (falls back to `name`) |
| `value` | `string` | `''` | Expected value to show children. If omitted, children are always shown. |

#### Example

```html
<!-- Minimal: registers the flag, always shows children -->
<vibe-flags-boolean name="darkMode">
  <div>Always visible</div>
</vibe-flags-boolean>

<!-- Show only when flag is true -->
<vibe-flags-boolean name="darkMode" description="Dark theme" value="true">
  <div>Dark mode active</div>
</vibe-flags-boolean>

<!-- Show only when flag is false -->
<vibe-flags-boolean name="darkMode" value="false">
  <div>Light mode active</div>
</vibe-flags-boolean>
```

### `<vibe-flags-select>`

Declares a select flag. Options are defined as `<vibe-flags-option>` children — only the active option's children are rendered. Starts as the first option.

#### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `string` | `''` | Unique flag identifier |
| `description` | `string` | `''` | Label shown in the toolbar (falls back to `name`) |

#### Example

```html
<vibe-flags-select name="hero" description="Hero section">
  <vibe-flags-option value="hero1"><h1>Welcome to V1</h1></vibe-flags-option>
  <vibe-flags-option value="hero2"><h1>Welcome to V2</h1></vibe-flags-option>
</vibe-flags-select>
```

### `<vibe-flags-option>`

A single option inside `<vibe-flags-select>`. Its children are shown only when this option is the active selection.

#### Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `value` | `string` | `''` | The option value |

### `<vibe-flags-toolbar>`

Floating toggle button + slide-out sidebar. Automatically discovers all registered flags and renders controls (toggle switches for booleans, dropdowns for selects). Uses Shadow DOM with `all: initial` on the host element — global page styles (font size, colors, spacing, etc.) cannot leak into the toolbar.

#### Example

```html
<vibe-flags-boolean name="beta" description="Beta features" value="true">
  <p>Beta content</p>
</vibe-flags-boolean>
<vibe-flags-toolbar></vibe-flags-toolbar>
```

---

## API Reference — Store

The `vibeFlagsStore` provides an imperative API for managing flags programmatically.

```ts
import { vibeFlagsStore } from 'vibe-flags';
```

### `register(config: VibeFlagsConfig)`

Register a single flag. Reads existing value from `localStorage`, falling back to `false` for booleans or the first option for selects. This is called automatically by `<vibe-flags-boolean>` and `<vibe-flags-select>` elements.

```ts
vibeFlagsStore.register({ key: 'beta', type: 'boolean', label: 'Beta Mode' });
vibeFlagsStore.register({ key: 'theme', type: 'select', options: ['light', 'dark'], label: 'Theme' });
```

### `unregister(key: string)`

Remove a flag from the store.

```ts
vibeFlagsStore.unregister('beta');
```

### `get(key: string): VibeFlagsValue | undefined`

Get the current value of a flag.

```ts
vibeFlagsStore.get('beta');  // false
vibeFlagsStore.get('theme'); // 'light'
```

### `set(key: string, value: VibeFlagsValue): void`

Set a flag value. Validates the value against the flag's type and options. Persists to `localStorage` and dispatches a change event.

```ts
vibeFlagsStore.set('beta', true);
vibeFlagsStore.set('theme', 'dark');

// Invalid values are silently ignored:
vibeFlagsStore.set('beta', 'yes');     // ignored (not a boolean)
vibeFlagsStore.set('theme', 'neon');   // ignored (not in options)
```

### `getAll(): VibeFlagsState`

Get all current flag values as a plain object.

```ts
vibeFlagsStore.getAll();
// { beta: false, theme: 'light' }
```

### `getConfig(): VibeFlagsConfig[]`

Get all registered flag configurations.

### `getConfigForKey(key: string): VibeFlagsConfig | undefined`

Get the configuration for a specific flag.

### `reset(): void`

Reset all flags to their initial values (`false` for booleans, first option for selects) and clear `localStorage`.

```ts
vibeFlagsStore.reset();
```

### Events

#### `vibe-flags-changed`

Dispatched on `window` whenever a flag value changes.

```ts
window.addEventListener('vibe-flags-changed', (e) => {
  const { key, state } = e.detail;
  console.log(`Flag "${key}" changed`);
  console.log('All flags:', state);
});
```

| Property | Type | Description |
|----------|------|-------------|
| `detail.key` | `string \| undefined` | The flag that changed, or `undefined` for bulk changes (reset) |
| `detail.state` | `VibeFlagsState` | Snapshot of all current flag values |

---

## API Reference — Types

All types are exported from the package:

```ts
import type {
  VibeFlagsConfig,
  VibeFlagsConfigBoolean,
  VibeFlagsConfigSelect,
  VibeFlagsValue,
  VibeFlagsState,
} from 'vibe-flags';
```

### `VibeFlagsConfigBoolean`

```ts
interface VibeFlagsConfigBoolean {
  key: string;
  type: 'boolean';
  label?: string;
}
```

### `VibeFlagsConfigSelect`

```ts
interface VibeFlagsConfigSelect {
  key: string;
  type: 'select';
  options: string[];
  label?: string;
}
```

### `VibeFlagsConfig`

```ts
type VibeFlagsConfig = VibeFlagsConfigBoolean | VibeFlagsConfigSelect;
```

### `VibeFlagsValue`

```ts
type VibeFlagsValue = boolean | string;
```

### `VibeFlagsState`

```ts
interface VibeFlagsState {
  [key: string]: VibeFlagsValue;
}
```

---

## Examples

### Basic Usage

```html
<!DOCTYPE html>
<html>
<head>
  <title>Vibe Flags Demo</title>
  <script type="module" src="https://unpkg.com/@vibe-flags/core"></script>
</head>
<body>
  <h1>My App</h1>

  <vibe-flags-boolean name="showBanner" description="Show welcome banner" value="true">
    <div style="padding: 16px; background: #dbeafe; border-radius: 8px;">
      Welcome to the beta! This banner is controlled by a feature flag.
    </div>
  </vibe-flags-boolean>

  <vibe-flags-toolbar></vibe-flags-toolbar>
</body>
</html>
```

### Multiple Boolean Flags

```html
<script type="module" src="https://unpkg.com/@vibe-flags/core"></script>

<vibe-flags-boolean name="darkMode" description="Dark Mode" value="true">
  <style>body { background: #1a1a1a; color: white; }</style>
</vibe-flags-boolean>

<vibe-flags-boolean name="showDebug" description="Debug Panel" value="true">
  <pre style="background: #fef3c7; padding: 12px; border-radius: 6px;">
    Debug info appears here
  </pre>
</vibe-flags-boolean>

<vibe-flags-boolean name="newNavbar" description="New Navbar" value="true">
  <nav style="background: #6366f1; color: white; padding: 12px;">
    New Navigation Bar
  </nav>
</vibe-flags-boolean>

<vibe-flags-boolean name="newNavbar" value="false">
  <nav style="background: gray; padding: 12px;">
    Old Navigation Bar
  </nav>
</vibe-flags-boolean>

<vibe-flags-toolbar></vibe-flags-toolbar>
```

### Select Flags — Layout Selector

```html
<script type="module" src="https://unpkg.com/@vibe-flags/core"></script>

<vibe-flags-select name="layout" description="Layout mode">
  <vibe-flags-option value="grid">
    <div style="display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px;">
      <div style="background: #f3f4f6; padding: 20px;">Card 1</div>
      <div style="background: #f3f4f6; padding: 20px;">Card 2</div>
      <div style="background: #f3f4f6; padding: 20px;">Card 3</div>
    </div>
  </vibe-flags-option>

  <vibe-flags-option value="list">
    <div style="display: flex; flex-direction: column; gap: 8px;">
      <div style="background: #f3f4f6; padding: 12px;">Item 1</div>
      <div style="background: #f3f4f6; padding: 12px;">Item 2</div>
      <div style="background: #f3f4f6; padding: 12px;">Item 3</div>
    </div>
  </vibe-flags-option>

  <vibe-flags-option value="table">
    <table style="width: 100%; border-collapse: collapse;">
      <tr><td style="border: 1px solid #e5e7eb; padding: 8px;">Row 1</td></tr>
      <tr><td style="border: 1px solid #e5e7eb; padding: 8px;">Row 2</td></tr>
      <tr><td style="border: 1px solid #e5e7eb; padding: 8px;">Row 3</td></tr>
    </table>
  </vibe-flags-option>
</vibe-flags-select>

<vibe-flags-toolbar></vibe-flags-toolbar>
```

---

## React Integration

`@vibe-flags/core` includes React utilities under the `@vibe-flags/core/react` sub-path. React 18 or 19 is required as a peer dependency.

### `useVibeFlags()`

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

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

Reads the current value of a feature flag and re-renders the component whenever the flag changes (via the `vibe-flags-changed` window event).

### `VibeFlagsToolbar`

A React component that renders the Vibe Flags floating toolbar. No props required. Handles custom element registration automatically.

```tsx
import { VibeFlagsToolbar } from '@vibe-flags/core/react';

function App() {
  return (
    <>
      <MyContent />
      <VibeFlagsToolbar />
    </>
  );
}
```

### Examples

**Boolean flag (pre-registered):**

```tsx
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' }}>Hello</div>;
}
```

**Register from config:**

```tsx
import { useVibeFlags } from '@vibe-flags/core/react';

function ThemePicker() {
  const theme = useVibeFlags({
    key: 'theme',
    type: 'select',
    options: ['light', 'dark', 'auto'],
    default: 'light',
  });
  return <p>Current theme: {theme}</p>;
}
```

**Full example with `VibeFlagsToolbar`:**

```tsx
import { useVibeFlags, VibeFlagsToolbar } from '@vibe-flags/core/react';

function App() {
  const showBanner = useVibeFlags({ key: 'showBanner', type: 'boolean', default: true });
  return (
    <>
      {showBanner && <div className="banner">Welcome to the beta!</div>}
      <VibeFlagsToolbar />
    </>
  );
}
```

### `VibeFlagsBoolean`

React wrapper for `<vibe-flags-boolean>`. Renders children when the flag matches `value`.

```tsx
import { VibeFlagsBoolean } from '@vibe-flags/core/react';

<VibeFlagsBoolean name="darkMode" value="true">
  <style>{`body { background: #1a1a1a; }`}</style>
</VibeFlagsBoolean>
```

Props: `name` (required), `description`, `value`, `default` (boolean), `children`.

### `VibeFlagsSelect` and `VibeFlagsOption`

React wrappers for `<vibe-flags-select>` / `<vibe-flags-option>`. Only the active option renders.

```tsx
import { VibeFlagsSelect, VibeFlagsOption } from '@vibe-flags/core/react';

<VibeFlagsSelect name="theme" default="light">
  <VibeFlagsOption value="light"><LightTheme /></VibeFlagsOption>
  <VibeFlagsOption value="dark"><DarkTheme /></VibeFlagsOption>
</VibeFlagsSelect>
```

`VibeFlagsSelect` props: `name` (required), `description`, `default`, `children`.
`VibeFlagsOption` props: `value` (required), `children`.

---

## Playground

An interactive playground is available under `/playground/`. Each example has its own page with a live StackBlitz embed — no install or build step required. Pages:

- `/playground/boolean-flag` — toggle a boolean flag on/off
- `/playground/select-flag` — switch between options with a select flag

---

## Source

- GitHub: https://github.com/Meldiron/vibe-flags
- npm: https://www.npmjs.com/package/@vibe-flags/core
- License: MIT