# Vibe Flags

> 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.

## 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>Welcome to the beta!</div>
</vibe-flags-boolean>

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

## Core Concepts

- **Boolean flags** (`<vibe-flags-boolean>`): On/off toggles, start as `false`
- **Select flags** (`<vibe-flags-select>` + `<vibe-flags-option>`): Multi-option picker, starts as first option
- **Toolbar** (`<vibe-flags-toolbar>`): Floating sidebar that auto-discovers all registered flags; draggable FAB snaps to corners, panel is resizable
- **Store API** (`vibeFlagsStore`): Imperative JS API for programmatic flag management

## Key Features

- No backend, no login, no config files
- ~11KB gzipped
- Framework-agnostic (React, Vue, Svelte, plain HTML)
- Persistent state via localStorage
- URL query parameter overrides (`?vf:<flag>=<value>`) — ephemeral, not saved to localStorage
- Reactive event system (`vibe-flags-changed` event)
- Full TypeScript support
- CSS-isolated toolbar via Shadow DOM (`all: initial`) — global page styles cannot bleed in

## Installation

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

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

## React Integration

Import `useVibeFlags` and `VibeFlagsToolbar` from `@vibe-flags/core/react` (React 18+ required):

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

function App() {
  const darkMode = useVibeFlags({ key: 'darkMode', type: 'boolean', default: false });
  return (
    <>
      <div>{darkMode ? 'Dark' : 'Light'}</div>
      <VibeFlagsToolbar />
    </>
  );
}
```

- **`useVibeFlags(key)`** — subscribe to a pre-registered flag by key
- **`useVibeFlags(config)`** — register a flag from config and subscribe
- **`VibeFlagsToolbar`** — renders the floating toolbar; optional `position` prop (`'bottom-right'` | `'bottom-left'` | `'top-right'` | `'top-left'`)
- **`VibeFlagsBoolean`** — wraps `<vibe-flags-boolean>`; props: `name`, `description`, `value`, `default`, `children`
- **`VibeFlagsSelect`** — wraps `<vibe-flags-select>`; props: `name`, `description`, `default`, `children`
- **`VibeFlagsOption`** — wraps `<vibe-flags-option>`; props: `value`, `children`

## Documentation

- [Getting Started](/docs/getting-started)
- [Flag Types](/docs/configuration)
- [React Integration](/docs/react)
- [Components API](/api/components)
- [Store API](/api/store)
- [Types](/api/types)
- [Comparison with LaunchDarkly, Unleash, PostHog](/docs/comparison)
- [Playground — Boolean Flag](/playground/boolean-flag)
- [Playground — Select Flag](/playground/select-flag)
- [Full documentation for LLMs](/llms-full.txt)

## Source

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