6. The Color Picker UI

Building a QuickPick with named presets, live swatches, and custom hue input.

The QuickPick API

VS Code’s showQuickPick is the standard way to present a list of choices to the user. It’s the same widget behind the Command Palette, file switcher, and symbol search. ColorIdentity uses it to build a color picker that adapts to the current mode.

The function signature tells the story:

export async function showColorPicker(
    currentHue: number,
    themeProfile: ThemeProfile,
    swatchDir: string,
    colorMode: ColorMode = 'simple'
): Promise<ColorPickResult | undefined>

The ColorPickResult carries the chosen hue and, in harmonized mode, the angular offset from the theme’s base hue:

export interface ColorPickResult {
    hue: number | null;
    harmonyOffset?: number;  // only set in harmonized mode
}

Three possible outcomes:

• { hue: 220 } — user picked a specific hue (simple mode preset or custom).
• { hue: 245, harmonyOffset: 25 } — user picked an analogous warm color in harmonized mode. The offset is stored so the color adapts on theme change.
• { hue: null } — user picked “Automatic.”
• undefined — user dismissed the picker without choosing.

Simple Mode vs. Harmonized Mode

The picker delegates to one of two internal functions based on the colorMode setting:

• Simple mode (showSimplePicker) — shows 14 fixed color presets spaced around the color wheel: Red, Orange, Yellow, Lime, Green, Mint, Teal, Cyan, Blue, Indigo, Purple, Magenta, Pink, Rose. These are absolute hues that don’t change with the theme.
• Harmonized mode (showHarmonizedPicker) — reads the theme’s base hue from themeAnalyzer.ts and generates suggestions grouped by color harmony: Analogous (±25°, ±40°), Complementary (~180°), Triadic (±120°), and Split-Complementary (±150°). Each suggestion carries an offset from the theme base, which gets persisted so the color relationship adapts on theme change.

Building the Picker Items

Each preset becomes a QuickPickItem with an icon, description, and optional “currently selected” indicator:

for (const preset of COLOR_PRESETS) {
    const previewHex = hslToHex(
        preset.hue,
        themeProfile.baseSaturation,
        themeProfile.baseLightness
    );
    const swatchUri = generateColorSwatch(swatchDir, previewHex);

    items.push({
        label: preset.label,
        description: `hue ${preset.hue}°  ·  ${previewHex}`,
        detail: currentHue === preset.hue
            ? '$(check) Currently selected' : undefined,
        iconPath: swatchUri,
        _hue: preset.hue,
    });
}

Several things happening here:

• Theme-aware previews: The swatch color uses the current theme’s saturation and lightness, so the preview shows what the color will actually look like in your editor — not a generic color swatch.
• PNG swatch icons: generateColorSwatch creates a 16×16 solid-color PNG file and returns its URI. QuickPick items support iconPath for displaying small images. We’ll see how these PNGs are generated in Section 7.
• Selection indicator: The $(check) syntax is a VS Code Codicon — a built-in icon set. It renders as a checkmark in the detail line.
• Custom property: _hue is a custom property added via a type intersection. It piggybacks the hue value on the QuickPick item so we can retrieve it when the user makes a selection.

Custom Hue Input

If the user picks “Custom Hue…”, the flow chains into an input box:

if ((picked as PickItem)._action === 'custom') {
    const input = await vscode.window.showInputBox({
        title: 'ColorIdentity: Custom Hue',
        prompt: 'Enter a hue value (0 = red, 120 = green, 240 = blue)',
        value: String(currentHue),
        validateInput: (value) => {
            const n = Number(value);
            if (isNaN(n) || n < 0 || n > 360) {
                return 'Please enter a number between 0 and 360';
            }
            return undefined;
        },
    });
    if (input === undefined) {
        return undefined;
    }
    return { hue: Number(input) };
}

The validateInput callback runs on every keystroke and shows an inline error message if the input is invalid. The user can’t submit an invalid value — the OK button is disabled while the validation message is visible. The value field pre-populates the input with the current hue, so the user can adjust from their current position rather than starting from scratch.