Skip to content

ColorPicker

HSV color picker with text input, preset swatches, and multiple output formats.

import { ColorPicker } from "phoundry-ui";

Basic (Hex)

Loading interactive example…

View source
basic-hex.svelte
<script lang="ts">
import { ColorPicker } from "phoundry-ui";
let hexColor = $state("#3b82f6");
</script>
<ColorPicker
value={hexColor}
onchange={(c: string) => {
hexColor = c;
}}
/>
<p class="mt-2 text-xs text-txt-tertiary">Value: {hexColor}</p>

Without Input & Presets

Loading interactive example…

View source
without-input-presets.svelte
<script lang="ts">
import { ColorPicker } from "phoundry-ui";
let minimalColor = $state("#ef4444");
</script>
<ColorPicker
value={minimalColor}
onchange={(c: string) => {
minimalColor = c;
}}
showInput={false}
showPresets={false}
/>
<p class="mt-2 text-xs text-txt-tertiary">Value: {minimalColor}</p>

Input field format (hex | rgb | hsl)

Loading interactive example…

View source
input-field-format-hex-rgb-hsl.svelte
<script lang="ts">
import { ColorPicker } from "phoundry-ui";
let rgbFlow = $state("#22c55e");
let hslFlow = $state("#a855f7");
</script>
<p class="mb-2 text-xs text-txt-secondary">
<code>format</code> switches the editable text representation and accepted
manual syntax.
<code>onchange</code> still passes a hex string for consistent storage -
convert locally if you need CSS <code>rgb()</code>/<code>hsl()</code>.
</p>
<div class="flex flex-col gap-4 sm:flex-row">
<div class="flex-1">
<p class="mb-1 text-[11px] font-medium text-txt-secondary">RGB</p>
<ColorPicker
value={rgbFlow}
onchange={(c: string) => {
rgbFlow = c;
}}
format="rgb"
/>
<p class="mt-1 text-[11px] text-txt-tertiary">state: {rgbFlow}</p>
</div>
<div class="flex-1">
<p class="mb-1 text-[11px] font-medium text-txt-secondary">HSL</p>
<ColorPicker
value={hslFlow}
onchange={(c: string) => {
hslFlow = c;
}}
format="hsl"
/>
<p class="mt-1 text-[11px] text-txt-tertiary">state: {hslFlow}</p>
</div>
</div>

Compact & disabled

Loading interactive example…

View source
compact-disabled.svelte
<script lang="ts">
import { ColorPicker } from "phoundry-ui";
let smallPicker = $state("#f97316");
let disabledPicker = $state("#64748b");
</script>
<div class="flex flex-wrap items-start gap-6">
<div>
<p class="mb-1 text-[11px] font-medium text-txt-secondary">
size=&quot;sm&quot;
</p>
<ColorPicker
value={smallPicker}
onchange={(c: string) => {
smallPicker = c;
}}
size="sm"
/>
</div>
<div>
<p class="mb-1 text-[11px] font-medium text-txt-secondary">disabled</p>
<ColorPicker value={disabledPicker} onchange={() => {}} disabled />
</div>
</div>

Custom presets

Loading interactive example…

View source
custom-presets.svelte
<script lang="ts">
import type { Component } from "svelte";
import { ColorPicker } from "phoundry-ui";
let presetDemo = $state("#06b6d4");
let managedPresets = $state([
{ id: "midnight", name: "Midnight", value: "#0f172a" },
{ id: "slate", name: "Slate", value: "#64748b" },
]);
type PickerPreset = { id: string; name: string; value: string };
type ExpandedPickerProps = {
value: string;
onchange: (value: string) => void;
format?: "hex" | "rgb" | "hsl";
showInput?: boolean;
showChannelSummary?: boolean;
showPresets?: boolean;
presetColors?: PickerPreset[];
recentColors?: string[];
customColors?: {
label: string;
description?: string;
colors: Array<{
id: string;
name: string;
value: string;
onpick: () => void;
}>;
};
onpresetadd?: (value: string) => void;
onpresetdelete?: (preset: PickerPreset) => void;
disabled?: boolean;
size?: "sm" | "md";
};
const ExpandedColorPicker =
ColorPicker as unknown as Component<ExpandedPickerProps>;
const themeColors = {
label: "Theme Colors",
description: "These colors match the active application theme.",
colors: [
{
id: "theme-blue",
name: "Blue",
value: "var(--option-blue)",
onpick: () => (presetDemo = "var(--option-blue)"),
},
{
id: "theme-green",
name: "Green",
value: "var(--option-green)",
onpick: () => (presetDemo = "var(--option-green)"),
},
{
id: "theme-pink",
name: "Pink",
value: "var(--option-pink)",
onpick: () => (presetDemo = "var(--option-pink)"),
},
],
};
</script>
<ExpandedColorPicker
value={presetDemo}
onchange={(c: string) => {
presetDemo = c;
}}
presetColors={managedPresets}
recentColors={["#f97316", "#8b5cf6"]}
customColors={themeColors}
onpresetadd={(value) => {
managedPresets = [
...managedPresets,
{ id: crypto.randomUUID(), name: value, value },
];
}}
onpresetdelete={(preset) => {
managedPresets = managedPresets.filter((item) => item.id !== preset.id);
}}
/>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
valuerequiredstring—Current color value.
onchangerequired(color: string) => void—Called when the color changes. The value is always normalized hex (e.g. #22c55e), including after typing in RGB/HSL form.
formatColorFormat'hex'How the text field displays and parses manual entry. Callbacks still receive hex.
showInputbooleantrueShow the text input for manual entry.
showPresetsbooleantrueShow the preset color swatches.
showChannelSummarybooleantrueShow the compact RGB and hue summary below the value field.
presetColorsColorPickerPreset[]DEFAULT_COLOR_PICKER_PRESETSControlled named presets. Omit for the defaults; pass [] to suppress them.
recentColorsstring[][]Controlled recent CSS colors, rendered in the provided order.
customColorsColorPickerCustomGroup—One labeled consumer-defined color group with item-owned pick callbacks.
onpresetadd(value: string) => void—Shows the dashed + control and requests that the normalized current color be added.
onpresetdelete(preset: ColorPickerPreset) => void—Enables right-click and Delete/Backspace preset removal requests.
disabledbooleanfalseDisable interaction.
size"sm" | "md"'md'Picker size.
classClassValue—Additional CSS classes.

Managed color sections

interface ColorPickerPreset {
id: string;
name: string;
value: string;
}
interface ColorPickerCustomItem {
id: string;
name: string;
value: string;
onpick: () => void;
}
interface ColorPickerCustomGroup {
label: string;
description?: string;
colors: ColorPickerCustomItem[];
}

presetColors, recentColors, and customColors are controlled. The picker requests preset mutations through onpresetadd and onpresetdelete; consumers own persistence and pass the updated arrays back.

Usage tips

  • Use format="rgb" or format="hsl" when authors prefer typing CSS functions - callbacks remain hex for a single canonical storage format.
  • Pass controlled presetColors to name and manage a consumer-owned palette. An empty array suppresses the built-in presets.
  • recentColors is presentation-only; persist, deduplicate, order, and cap recents in the consumer.
  • Use customColors for semantic or theme-backed CSS colors. Each custom item owns its callback, so it can preserve intent that a hex callback cannot represent.
  • Manual Hex, RGB, and HSL fields commit on blur or Enter. Escape or invalid/out-of-range input restores the current value.
  • Use size="sm" for inline usage in toolbars or compact UIs.
  • The picker uses HSV internally for intuitive color selection - hue on the slider, saturation/value on the area.

CSS styling

.ph-color-picker is the stable identification hook for ColorPicker. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.

data-size selects the existing sm 10rem and md 13.75rem picker geometry. Fixed HSV gradients consume --ph-color-space-white, --ph-color-space-black, and --ph-color-hue-spectrum from the shared stylesheet. These describe mathematical color channels independently of the active Theme.

Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.

CSS variables and browser-supported color functions, including color-mix() and oklch(), resolve through the browser. The picker refreshes external colors after committed theme changes and root style/appearance changes. Resolved external RGB values retain their precision rather than passing through rounded HSV coordinates.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.