Variant Picker

UI variant picker for AI coding agents. Let Claude Code, Codex, and other coding agents generate multiple design variants, then browse them visually and select the one you want. The source code updates automatically.

1. Install

pnpm add variant-picker

2. Add the plugin

React + Vite

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { variantPlugin } from "variant-picker/vite";

export default defineConfig({
  plugins: [variantPlugin(), react()],
});

Next.js

// next.config.mjs
import { withVariant } from "variant-picker/next";

export default withVariant({});

Astro

// astro.config.mjs
import { defineConfig } from "astro/config";
import { variantIntegration } from "variant-picker/astro";

export default defineConfig({
  integrations: [variantIntegration()],
});

3. Add to your agent instructions

Add the following to your CLAUDE.md, AGENTS.md, or equivalent file so your AI coding agent uses variant-picker when generating UI:

To offer multiple design variants for a UI component, use the
variant-picker package. Wrap the options in <Variant> and
<VariantItem> so the user can browse them visually in the dev
server and select the one they want.

React / Next.js:
import { Variant, VariantItem } from 'variant-picker'

Astro:
import Variant from 'variant-picker/astro/Variant.astro'
import VariantItem from 'variant-picker/astro/VariantItem.astro'

<Variant name="hero">
  <VariantItem label="Option A">...</VariantItem>
  <VariantItem label="Option B">...</VariantItem>
</Variant>

Each <Variant> must have a unique name. Variants can be nested.

Usage

Open your dev server. Each <Variant> group shows a floating toolbar:

• Left/right arrows to switch between variants
• Select button to keep the chosen variant

When you click Select, the <Variant> wrapper is removed from source code and only the selected child remains. The page updates automatically via HMR.

React / Next.js

import { Variant, VariantItem } from "variant-picker";

<Variant name="hero">
  <VariantItem label="Minimal">...</VariantItem>
  <VariantItem label="Bold">...</VariantItem>
</Variant>

Astro

---
import Variant from 'variant-picker/astro/Variant.astro'
import VariantItem from 'variant-picker/astro/VariantItem.astro'
---

<Variant name="hero">
  <VariantItem label="Minimal">...</VariantItem>
  <VariantItem label="Bold">...</VariantItem>
</Variant>

Native Astro components, no React dependency needed.

Nested variants

Variants can be nested. For example, a hero section variant can contain a nested CTA variant inside it:

<Variant name="hero">
  <VariantItem label="Centered">
    ...
    <Variant name="hero-cta">
      <VariantItem label="Single button">...</VariantItem>
      <VariantItem label="Two buttons">...</VariantItem>
    </Variant>
  </VariantItem>
  <VariantItem label="Left-aligned">...</VariantItem>
</Variant>

Each variant can be selected independently.

Keyboard shortcuts

| Key | Action | | --- | ---------------- | | ← | Previous variant | | → | Next variant |

Exports

| Import | Description | | ---------------------------------------- | --------------------------- | | variant-picker | React components (default) | | variant-picker/react | React components (explicit) | | variant-picker/vite | Vite plugin | | variant-picker/next | Next.js config wrapper | | variant-picker/astro | Astro integration | | variant-picker/astro/Variant.astro | Native Astro component | | variant-picker/astro/VariantItem.astro | Native Astro component | | variant-picker/core | Transform API and types |

Architecture

variant-picker
├── core/       # Source transform (AST for JSX, regex for templates)
├── react/      # React components (Variant, VariantItem)
├── astro/      # Native Astro components + integration
├── vite/       # Vite plugin (prop injection, HMR, dev middleware)
└── next/       # Next.js wrapper (webpack loader, sidecar dev server)

The core transform supports both JSX/TSX (via Babel AST) and template languages like Astro (via regex). React and Astro are supported today, with Vue and Svelte planned.

License

MIT