Beste UI Components
componentinspector-filterssource: ok · hit
Inspector Filters
Settings row for a CSS filter stack, all ten functions of it: the row shows the whole stack applied to something, and opens an editor holding the nine numeric filters as rows of the family plus a drop shadow section, over a preview large enough to judge.
npx shadcn add "https://ui.beste.co/component/r/inspector-filters.json"free
No selection tags yet — empty means no evidence, not lack of support.
Dependencies
Bundle weight · lightclsxtailwind-mergelucide-react
Registry dependencies
popoverbuttoninputtabs
Files4 · source cached 10/8/2026, 9:40:36 PM
registry-components/inspector-filters/inspector-filters.tsx
"use client";
import { CheckIcon, CopyIcon, type LucideIcon } from "lucide-react";
import * as React from "react";
import { InspectorColor } from "@/components/beste/component/inspector-color";
import { InspectorSlider } from "@/components/beste/component/inspector-slider";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
import { cn } from "@/lib/utils";
/** Surface treatment of the row. Mirrors inspector-slider. */
type Tone = "muted" | "outline" | "ghost";
/** Row height preset. Mirrors inspector-slider. */
type Size = "sm" | "default" | "lg";
/** The row itself presses, so it answers hover like any other trigger in the family. */
const toneStyles: Record<Tone, string> = {
muted: "border border-transparent bg-muted hover:bg-muted-foreground/15",
outline: "border border-border hover:bg-muted",
ghost: "border border-transparent hover:border-border hover:bg-muted",
};
const sizeStyles: Record<Size, string> = {
sm: "[--inspector-height:--spacing(8)] [--inspector-pad:--spacing(2.5)]",
default: "[--inspector-height:--spacing(9)] [--inspector-pad:--spacing(3)]",
lg: "[--inspector-height:--spacing(11)] [--inspector-pad:--spacing(4)]",
};
/**
* The picture the preview is filtered. A gradient rather than a photograph, so the
* component carries no asset and works offline: it has a hue sweep for saturate and
* hue-rotate to act on, and light and dark ends for brightness and contrast.
*/
const PREVIEW_IMAGE =
"linear-gradient(120deg, #0f172a 0%, #fb7185 35%, #fdba74 55%, #22d3ee 80%, #f8fafc 100%)";
/** The one filter that is not a single number: an offset, a blur and a colour. */
interface DropShadowValue {
/** Horizontal offset in px. */
x?: number;
/** Vertical offset in px. */
y?: number;
/** Blur radius in px. Unlike a box shadow, there is no spread and no inset. */
blur?: number;
/** Any CSS colour, alpha included. */
color?: string;
}
/**
* A filter stack, in the pieces CSS takes it in — all ten of them. Each one is at
* its own no-op by default, which is what lets the row say "None" without a
* separate flag, and what keeps the written stack down to what was actually changed.
*/
interface FiltersValue {
/** Blur radius in px. */
blur?: number;
/** Brightness in percent, where 100 is unchanged. */
brightness?: number;
/** Contrast in percent, where 100 is unchanged. */
contrast?: number;
/** Saturation in percent, where 100 is unchanged. */
saturate?: number;
/** Hue rotation in degrees. */
hueRotate?: number;
/** Greyscale in percent, where 0 is unchanged. */
grayscale?: number;
/** Inversion in percent, where 0 is unchanged. */
invert?: number;
/** Sepia in percent, where 0 is unchanged. */
sepia?: number;
/** Opacity in percent, where 100 is unchanged. */
opacity?: number;
/**
* A shadow cast by the shape rather than the box, which is the whole reason it is
* a filter and not a `box-shadow`: it follows a PNG's transparency or an SVG's
* outline. Left out of the stack until it is given something to draw.
*/
dropShadow?: DropShadowValue;
}
/** Every key the stack understands, `dropShadow` included. */
type FilterKey = keyof FiltersValue;
interface Piece {
/** Numeric pieces only; `dropShadow` is handled on its own. */
key: Exclude<FilterKey, "dropShadow">;
label: string;
/** The value at which this piece does nothing. */
neutral: number;
min: number;
max: number;
step: number;
/** How the number reads, and how it is written into `filter`. */
unit: "px" | "%" | "deg";
}
/*
* In the order CSS applies them, which is the order they are written. The three
* that only ever wash a picture out — greyscale, sepia, invert — sit after the ones
* that shape it, and opacity comes last of the numbers because it acts on whatever
* the others left behind.
*
* The ranges are not all 0 to 200: brightness, contrast and saturation are
* multipliers with no ceiling in the spec, while greyscale, sepia, invert and
* opacity are fractions that the spec itself clamps at 100%. A slider that lets a
* reader ask for 150% greyscale is a slider that lies to them.
*/
const PIECES: Piece[] = [
{ key: "blur", label: "Blur", neutral: 0, min: 0, max: 40, step: 0.5, unit: "px" },
{ key: "brightness", label: "Brightness", neutral: 100, min: 0, max: 200, step: 1, unit: "%" },
{ key: "contrast", label: "Contrast", neutral: 100, min: 0, max: 200, step: 1, unit: "%" },
{ key: "saturate", label: "Saturation", neutral: 100, min: 0, max: 200, step: 1, unit: "%" },
{ key: "hueRotate", label: "Hue", neutral: 0, min: 0, max: 360, step: 1, unit: "deg" },
{ key: "grayscale", label: "Grayscale", neutral: 0, min: 0, max: 100, step: 1, unit: "%" },
{ key: "sepia", label: "Sepia", neutral: 0, min: 0, max: 100, step: 1, unit: "%" },
{ key: "invert", label: "Invert", neutral: 0, min: 0, max: 100, step: 1, unit: "%" },
{ key: "opacity", label: "Opacity", neutral: 100, min: 0, max: 100, step: 1, unit: "%" },
];
const DEFAULT_SHADOW: Required<DropShadowValue> = {
x: 0,
y: 0,
blur: 0,
color: "#00000040",
};
/** How long the copy button stays ticked, in ms. */
const COPIED_MS = 1400;
/** The CSS function each piece is written as. */
const CSS_NAMES: Record<Exclude<FilterKey, "dropShadow">, string> = {
blur: "blur",
brightness: "brightness",
contrast: "contrast",
saturate: "saturate",
hueRotate: "hue-rotate",
grayscale: "grayscale",
sepia: "sepia",
invert: "invert",
opacity: "opacity",
};
function amount(value: FiltersValue, piece: Piece) {
return value[piece.key] ?? piece.neutral;
}
function shadowOf(value: FiltersValue) {
return { ...DEFAULT_SHADOW, ...value.dropShadow };
}
/**
* A shadow with no offset and no blur is a shadow nobody can see, whatever colour it
* is, so that is this piece's no-op — the same rule the numbers follow, rather than
* a flag saying whether it counts.
*/
function hasShadow(value: FiltersValue) {
const shadow = shadowOf(value);
return shadow.x !== 0 || shadow.y !== 0 || shadow.blur !== 0;
}
/**
* The `filter` this describes. Pieces sitting at their no-op are left out rather
* than written as `brightness(100%)`: the shortest honest string is also the one a
* reader can check at a glance, and `none` is what CSS calls an empty stack.
*
* The shadow is written last, after the numbers, because it should fall from the
* picture the rest of the stack produced and not from the one it started as.
*/
function toCss(value: FiltersValue, pieces: Piece[], shadow: boolean): string {
const written = pieces
.filter((piece) => amount(value, piece) !== piece.neutral)
.map((piece) => {
const raw = amount(value, piece);
const printed = piece.unit === "%" ? `${raw}%` : `${raw}${piece.unit}`;
return `${CSS_NAMES[piece.key]}(${printed})`;
});
if (shadow && hasShadow(value)) {
const { x, y, blur, color } = shadowOf(value);
written.push(`drop-shadow(${x}px ${y}px ${blur}px ${color})`);
}
return written.length > 0 ? written.join(" ") : "none";
}
interface InspectorFiltersProps {
/** Label rendered on the left, inside the row. */
label: string;
/** Optional leading icon shown before the label. */
icon?: LucideIcon;
/** Controlled value. Pair it with `onValueChange`. */
value?: FiltersValue;
/** Initial value in uncontrolled mode. */
defaultValue?: FiltersValue;
/** Fires on every adjustment, including each frame of a drag. */
onValueChange?: (value: FiltersValue) => void;
/**
* Fires once an adjustment is finished — a slider released. Use it for work too
* expensive to run per frame.
*/
onValueCommit?: (value: FiltersValue) => void;
/** Fires when the editor opens or closes. */
onOpenChange?: (open: boolean) => void;
/**
* Which pieces to offer. Leaving one out also leaves it out of the CSS, so a
* caller cannot end up shipping a value nobody can edit. The order is always the
* one CSS applies them in, not the order given here.
* @defaultValue the nine numeric filters, and the drop shadow */
pieces?: FilterKey[];
/** Notation the shadow's colour is written back in. */
format?: "hex" | "oklch" | "rgb";
/**
* What the preview is filtered. Any CSS image: pass the picture this stack will
* actually be applied to and the editor stops being a demonstration.
*/
preview?: string;
/** Block interaction and dim the row. */
disabled?: boolean;
/**
* Surface treatment: filled (default), hairline outline, or bare until hover.
* @defaultValue "muted" */
tone?: Tone;
/**
* Row height preset.
* @defaultValue "default" */
size?: Size;
className?: string;
/** Accessible name. Falls back to `label`. */
"aria-label"?: string;
}
export const inspectorFiltersDemo: InspectorFiltersProps = {
label: "Filters",
className: "w-72",
defaultValue: { brightness: 105, contrast: 110, saturate: 120, sepia: 15 },
};
export function InspectorFilters({
label,
icon: Icon,
value: valueProp,
defaultValue,
onValueChange,
onValueCommit,
onOpenChange,
pieces,
format = "hex",
preview = PREVIEW_IMAGE,
disabled = false,
tone = "muted",
size = "default",
className,
"aria-label": ariaLabel,
}: InspectorFiltersProps) {
const [internalValue, setInternalValue] = React.useState<FiltersValue>(defaultValue ?? {});
const value = valueProp ?? internalValue;
const valueRef = React.useRef(value);
valueRef.current = value;
const active = React.useMemo(
() => (pieces ? PIECES.filter((piece) => pieces.includes(piece.key)) : PIECES),
[pieces],
);
const withShadow = pieces ? pieces.includes("dropShadow") : true;
const shadow = shadowOf(value);
const writeShadow = (patch: Partial<DropShadowValue>, complete: boolean) => {
write({ dropShadow: { ...shadowOf(valueRef.current), ...patch } }, complete);
};
const write = (patch: Partial<FiltersValue>, complete: boolean) => {
const next = { ...valueRef.current, ...patch };
valueRef.current = next;
if (valueProp === undefined) setInternalValue(next);
onValueChange?.(next);
if (complete) onValueCommit?.(next);
};
const css = toCss(value, active, withShadow);
const changed =
active.filter((piece) => amount(value, piece) !== piece.neutral).length +
(withShadow && hasShadow(value) ? 1 : 0);
/*
* Copying reports back rather than assuming: the tick only appears once the
* clipboard has actually taken the string, since a browser may refuse it and a
* tick that lied would be worse than no tick. Same handler as inspector-easing's,
* kept here rather than shared, for the same reason the tone and size tables are.
*/
const [copied, setCopied] = React.useState(false);
React.useEffect(() => {
if (!copied) return;
const timer = window.setTimeout(() => setCopied(false), COPIED_MS);
return () => window.clearTimeout(timer);
}, [copied]);
const copy = async () => {
try {
await navigator.clipboard.writeText(css);
setCopied(true);
} catch {
// No clipboard, or permission refused. The value is on screen either way.
}
};
return (
<Popover onOpenChange={onOpenChange}>
{/*
The row is the trigger, so the editor can take the trigger width and open
flush with it. What the row shows is the stack applied to something, because
four numbers do not add up to an impression and a filter is nothing but one.
*/}
<PopoverTrigger asChild>
<button
type="button"
disabled={disabled}
aria-label={ariaLabel}
data-slot="inspector-filters"
data-disabled={disabled}
className={cn(
"group/inspector-filters flex w-full cursor-pointer items-center gap-2 text-left",
"h-(--inspector-height) rounded-(--inspector-radius) px-(--inspector-pad)",
"[--inspector-radius:var(--radius-xl)] transition-colors",
"outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background",
"data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50",
sizeStyles[size],
toneStyles[tone],
className,
)}
>
<span
data-slot="inspector-filters-label"
className="flex min-w-0 items-center gap-1.5 text-sm font-medium text-foreground/70 select-none"
>
{Icon ? <Icon className="size-4 shrink-0" /> : null}
<span className="truncate">{label}</span>
</span>
<span className="ml-auto flex min-w-0 items-center gap-2">
<span
data-slot="inspector-filters-summary"
className={cn(
"truncate text-sm font-medium select-none",
changed === 0 ? "text-foreground/70" : "text-foreground",
)}
>
{changed === 0 ? "None" : `${changed} active`}
</span>
<span
aria-hidden="true"
data-slot="inspector-filters-preview"
className="size-5 shrink-0 overflow-hidden rounded-sm border border-border"
>
{/* The filter goes on an inner layer: filtering the box would take its
own border with it. */}
<span
className="block size-full"
style={{ backgroundImage: preview, filter: css === "none" ? undefined : css }}
/>
</span>
</span>
</button>
</PopoverTrigger>
<PopoverContent
align="start"
side="bottom"
sideOffset={8}
// Three parts, not one scrolling column: the panel itself does not scroll, so
// the preview and the string stay where they are while the settings between
// them move. A fixed cap rather than the popover's own available-height
// variable, which the Base UI variant has no equivalent for.
className="flex max-h-[min(20rem,45vh)] w-[var(--radix-popover-trigger-width)] min-w-64 flex-col overflow-hidden p-0"
>
{/*
The preview, pinned: it is the only thing here worth judging, and a filter is
judged while the slider is moving. Scrolling it away at the moment it matters
most is the one thing this panel must not do — which is also why it is kept
shallow, since anything pinned inside a short panel is taken from the list.
*/}
<div className="shrink-0 p-2">
<div
aria-hidden="true"
data-slot="inspector-filters-preview-large"
className="h-16 w-full overflow-hidden rounded-lg border border-border"
>
<span
className="block size-full"
style={{ backgroundImage: preview, filter: css === "none" ? undefined : css }}
/>
</div>
</div>
{/*
The settings scroll. Ten filters is more than a panel can hold at once, and
`min-h-0` is what lets this shrink inside the column: a flex child defaults
to its content's height and would otherwise push the footer off the bottom
instead of scrolling.
*/}
<div
data-slot="inspector-filters-scroll"
className="min-h-0 flex-1 overflow-y-auto px-2 pb-2"
>
{/* The editor is the family stacked up, in the order CSS applies them. */}
<div className="flex flex-col gap-1">
{active.map((piece) => (
<InspectorSlider
key={piece.key}
label={piece.label}
size="sm"
min={piece.min}
max={piece.max}
step={piece.step}
ticks={false}
value={amount(value, piece)}
onValueChange={(next) => write({ [piece.key]: next }, false)}
onValueCommit={(next) => write({ [piece.key]: next }, true)}
formatValue={(next) =>
piece.unit === "%" ? `${Math.round(next)}%` : `${next}${piece.unit}`
}
/>
))}
</div>
{/*
The shadow gets a section of its own, since it is four settings rather than
one and would otherwise read as four unrelated sliders at the bottom of the
list. No spread and no inset here, unlike inspector-shadow: `drop-shadow()`
has neither, and offering knobs CSS will ignore is worse than not having
them.
*/}
{withShadow ? (
<div className="mt-2 flex flex-col gap-1 border-t border-border pt-2">
<span
data-slot="inspector-filters-shadow-label"
className="px-3 text-sm font-medium text-foreground/70 select-none"
>
Drop shadow
</span>
<InspectorSlider
label="Offset X"
size="sm"
min={-40}
max={40}
step={1}
ticks={false}
value={shadow.x}
onValueChange={(next) => writeShadow({ x: next }, false)}
onValueCommit={(next) => writeShadow({ x: next }, true)}
formatValue={(next) => `${Math.round(next)}px`}
/>
<InspectorSlider
label="Offset Y"
size="sm"
min={-40}
max={40}
step={1}
ticks={false}
value={shadow.y}
onValueChange={(next) => writeShadow({ y: next }, false)}
onValueCommit={(next) => writeShadow({ y: next }, true)}
formatValue={(next) => `${Math.round(next)}px`}
/>
<InspectorSlider
label="Shadow blur"
size="sm"
min={0}
max={40}
step={1}
ticks={false}
value={shadow.blur}
onValueChange={(next) => writeShadow({ blur: next }, false)}
onValueCommit={(next) => writeShadow({ blur: next }, true)}
formatValue={(next) => `${Math.round(next)}px`}
/>
<InspectorColor
label="Shadow color"
size="sm"
alpha
format={format}
value={shadow.color}
onValueChange={(next) => writeShadow({ color: next }, false)}
onValueCommit={(next) => writeShadow({ color: next }, true)}
/>
</div>
) : null}
</div>
{/*
The string itself, which is the one part of a filter stack that is easy to
get wrong by hand: the order matters, and so does leaving the no-ops out.
Hence a way to take it, and hence it staying put while the settings scroll —
a copy button that has to be scrolled to is a copy button nobody finds.
*/}
<div className="group/inspector-filters-css flex shrink-0 items-center gap-1 border-t border-border p-2">
<span
data-slot="inspector-filters-css"
className="min-w-0 flex-1 truncate text-sm text-foreground/70 select-none"
>
{css}
</span>
<button
type="button"
onClick={copy}
aria-label={copied ? "Copied" : "Copy to clipboard"}
title={copied ? "Copied" : "Copy"}
data-slot="inspector-filters-copy"
className={cn(
"flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-md",
"text-foreground/70 transition-colors hover:bg-foreground/10 hover:text-foreground",
"opacity-0 outline-none group-hover/inspector-filters-css:opacity-100 focus-visible:opacity-100",
"focus-visible:ring-2 focus-visible:ring-ring/50",
// Once it has done its job it stays put, so the mark that says so is
// not pulled out from under the pointer.
copied && "opacity-100",
)}
>
{copied ? <CheckIcon className="size-3.5" /> : <CopyIcon className="size-3.5" />}
</button>
</div>
</PopoverContent>
</Popover>
);
}
registry-components/inspector-slider/inspector-slider.tsx
"use client";
import type { LucideIcon } from "lucide-react";
import * as React from "react";
import { cn } from "@/lib/utils";
/** Surface treatment of the row. */
type Tone = "muted" | "outline" | "ghost";
/** Row height preset. */
type Size = "sm" | "default" | "lg";
/* -------------------------------------------------------------------------- */
/* Interaction tuning */
/* -------------------------------------------------------------------------- */
/** Pointer travel (CSS px) before a press stops being a click and becomes a drag. */
const DRAG_THRESHOLD = 3;
/** Cursor distance past the row edge that is ignored before the band stretches. */
const OVERDRAG_DEAD_ZONE = 32;
/** Cursor distance past the dead zone that maps to the full stretch. */
const OVERDRAG_RANGE = 200;
/** Widest the rubber band pulls, in px. */
const OVERDRAG_MAX = 8;
/** Drag sensitivity while Shift is held (precision mode). */
const PRECISION_FACTOR = 0.25;
/** Keyboard and wheel multiplier while Shift is held (coarse mode). */
const COARSE_FACTOR = 10;
/** Normalized distance within which the value is magnetically pulled to a tick. */
const SNAP_RADIUS = 0.03;
/** Trailing idle time (ms) before a wheel gesture counts as committed. */
const WHEEL_COMMIT_DELAY = 180;
/**
* Window in which two clicks count as one sequence. Used to remember the value
* from before a double-click, since `PointerEvent.detail` is specified as 0 and
* cannot be relied on for a click count.
*/
const DOUBLE_CLICK_WINDOW = 500;
/** Gap kept between the handle and the label/readout before the handle gives way. */
const CROWD_BUFFER = 8;
/** Handle width in px. Mirrors the `w-1` utility on the handle element. */
const HANDLE_WIDTH = 4;
/** Distance the handle keeps from the rounded ends of the track. */
const HANDLE_INSET = 4;
/**
* Spring-shaped easing sampled from a lightly under-damped spring. Click jumps,
* keyboard steps and the rubber-band release all run on plain CSS transitions
* with this curve (420ms, matching the `duration-[420ms]` utilities below), so
* the component needs no animation library and the motion stays on the
* compositor.
*/
const SPRING_EASE =
"linear(0, 0.014, 0.056 3.4%, 0.216 7.2%, 0.472 11.6%, 0.72 16%, 0.895 20%, 0.986 23.6%, 1.036 27.8%, 1.045 32.4%, 1.026 39.4%, 0.998 46.6%, 0.992 52.4%, 1.001 66.4%, 1)";
/** Fallback snap targets for continuous ranges: every decile plus both ends. */
const DECILE_FRACTIONS = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9];
/* -------------------------------------------------------------------------- */
/* Helpers */
/* -------------------------------------------------------------------------- */
/** The measuring effects must not warn while this client component renders on the server. */
const useIsomorphicLayoutEffect =
typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
function clamp(value: number, lo: number, hi: number) {
return Math.min(hi, Math.max(lo, value));
}
/**
* Decimal places implied by `step`, so a 0.05 step formats as "0.55" instead of
* "0.5500000000000001". Handles exponential notation (1e-4) as well.
*/
function stepDecimals(step: number) {
if (!Number.isFinite(step) || step <= 0) return 2;
const text = String(step);
const exponent = /e-(\d+)$/.exec(text);
if (exponent) {
const mantissaDecimals = text.split("e")[0]?.split(".")[1]?.length ?? 0;
return Number(exponent[1]) + mantissaDecimals;
}
const dot = text.indexOf(".");
return dot === -1 ? 0 : text.length - dot - 1;
}
const toneStyles: Record<Tone, { surface: string; fill: string }> = {
muted: {
surface: "bg-muted",
fill: "bg-muted-foreground/10 group-data-[active=true]/inspector-slider:bg-muted-foreground/20",
},
outline: {
surface: "border border-border",
fill: "bg-muted group-data-[active=true]/inspector-slider:bg-muted-foreground/15",
},
ghost: {
surface: "border border-transparent group-data-[active=true]/inspector-slider:border-border",
fill: "bg-muted",
},
};
const sizeStyles: Record<Size, string> = {
sm: "[--inspector-height:--spacing(8)] [--inspector-pad:--spacing(2.5)]",
default: "[--inspector-height:--spacing(9)] [--inspector-pad:--spacing(3)]",
lg: "[--inspector-height:--spacing(11)] [--inspector-pad:--spacing(4)]",
};
/** Geometry and modifier state captured for the lifetime of one pointer gesture. */
interface DragSession {
pointerId: number;
startX: number;
startY: number;
/** Row geometry captured on press, so mid-drag layout shifts cannot warp the math. */
left: number;
right: number;
/** Unscaled (CSS pixel) width of the row. */
width: number;
/** Scale factor of any ancestor transform — block previews scale their canvas. */
scale: number;
dragging: boolean;
/** Whether Shift was held on the most recent frame (precision drag). */
precise: boolean;
/**
* Cursor x and normalized position at the moment precision mode last changed.
* Anchoring on the drawn fraction rather than on the (step-quantized) value
* keeps the handle from hopping onto the grid when Shift is pressed.
*/
anchorX: number;
anchorFraction: number;
}
/* -------------------------------------------------------------------------- */
/* Props */
/* -------------------------------------------------------------------------- */
interface InspectorSliderProps {
/** Label rendered on the left, inside the row. */
label: string;
/** Optional leading icon shown before the label. */
icon?: LucideIcon;
/** Controlled value. Pair it with `onValueChange`. */
value?: number;
/** Initial value in uncontrolled mode. Falls back to `min`. */
defaultValue?: number;
/** Fires on every drag frame, click, key press, wheel tick and typed edit. */
onValueChange?: (value: number) => void;
/**
* Fires once when a gesture ends and the value actually changed (pointer
* release, key release, end of a wheel burst, typed edit). Use it for
* expensive work such as persisting or re-rendering a WebGL scene.
*/
onValueCommit?: (value: number) => void;
/**
* Minimum value.
* @defaultValue 0 */
min?: number;
/**
* Maximum value.
* @defaultValue 1 */
max?: number;
/**
* Smallest increment. Also drives readout precision and keyboard steps.
* @defaultValue 0.01 */
step?: number;
/** Format the readout. Defaults to `value.toFixed(...)` plus `unit`. */
formatValue?: (value: number) => string;
/** Suffix appended to the default readout, e.g. "%", "px", "°". */
unit?: string;
/**
* Tick marks inside the track: `true` for automatic (one per step up to 12,
* otherwise deciles), a count, an explicit list of values, or `false`.
* @defaultValue true */
ticks?: boolean | number | number[];
/**
* Magnetically pull a click to the nearest tick. Dragging is never snapped —
* it stays continuous and only `step` quantizes it.
* @defaultValue true */
snap?: boolean;
/** Allow an exact value to be typed in, by double-clicking the row or pressing Enter. */
editable?: boolean;
/**
* Adjust the value with the wheel while the row has keyboard focus.
* @defaultValue true */
wheel?: boolean;
/** Value restored by Alt-click. Falls back to `defaultValue`, then `min`. */
resetValue?: number;
/** Block every interaction and dim the row. */
disabled?: boolean;
/**
* Keep the handle and the tick marks on show while the row sits idle, instead
* of revealing them on hover. For a row whose value has to read at a glance,
* or a panel where every row should look the same before it is touched.
* @defaultValue false */
revealed?: boolean;
/**
* Surface treatment: filled (default), hairline outline, or bare until hover.
* @defaultValue "muted" */
tone?: Tone;
/**
* Row height preset.
* @defaultValue "default" */
size?: Size;
/** Name of the underlying range input, so the row can take part in a form. */
name?: string;
/** Id of the underlying range input, for an external `<label htmlFor>`. */
id?: string;
className?: string;
/**
* Classes for the label. Needed when the row sits on something other than a
* theme surface — a colour ramp, say — and the muted default stops being
* legible. Merged onto the element, so a text colour here simply wins.
*/
labelClassName?: string;
/**
* Classes for the value readout. Note that the readout brightens to
* `text-foreground` while the row is engaged, so an override that must hold
* during hover and drag has to restate itself:
* `"text-white group-data-[active=true]/inspector-slider:text-white"`.
*/
valueClassName?: string;
/** Accessible name. Falls back to `label`. */
"aria-label"?: string;
}
export const inspectorSliderDemo: InspectorSliderProps = {
label: "Blend",
className: "w-72",
min: 0,
max: 1,
step: 0.01,
defaultValue: 0.55,
editable: true,
};
/* -------------------------------------------------------------------------- */
/* Component */
/* -------------------------------------------------------------------------- */
export function InspectorSlider({
label,
icon: Icon,
value: valueProp,
defaultValue,
onValueChange,
onValueCommit,
min = 0,
max = 1,
step = 0.01,
formatValue,
unit,
ticks = true,
snap = true,
editable = false,
wheel = true,
resetValue,
disabled = false,
revealed = false,
tone = "muted",
size = "default",
name,
id,
className,
labelClassName,
valueClassName,
"aria-label": ariaLabel,
}: InspectorSliderProps) {
const span = max - min || 1;
const decimals = React.useMemo(() => stepDecimals(step), [step]);
const rootRef = React.useRef<HTMLDivElement>(null);
const labelRef = React.useRef<HTMLSpanElement>(null);
const readoutRef = React.useRef<HTMLSpanElement>(null);
const inputRef = React.useRef<HTMLInputElement>(null);
const editRef = React.useRef<HTMLInputElement>(null);
/**
* Props that internal callbacks read but must not depend on. Keeping them in
* a ref lets every handler below stay referentially stable even when the
* parent passes fresh inline callbacks on each render.
*/
const latest = React.useRef({ onValueChange, onValueCommit, formatValue });
useIsomorphicLayoutEffect(() => {
latest.current = { onValueChange, onValueCommit, formatValue };
});
const quantize = React.useCallback(
(raw: number) => {
const bounded = clamp(raw, min, max);
if (!(step > 0)) return bounded;
const stepped = min + Math.round((bounded - min) / step) * step;
return clamp(Number(stepped.toFixed(decimals)), min, max);
},
[min, max, step, decimals],
);
const format = React.useCallback(
(value: number) => {
const custom = latest.current.formatValue;
return custom ? custom(value) : `${value.toFixed(decimals)}${unit ?? ""}`;
},
[decimals, unit],
);
/**
* Value rendered by React. In controlled mode it tracks the prop; in
* uncontrolled mode it is the mount value and never changes again — every
* later update is written straight to the DOM, so dragging costs zero
* renders. React only rewrites an attribute when its own previous and next
* values differ, so those imperative writes are never clobbered.
*/
const renderValue = quantize(valueProp ?? defaultValue ?? min);
const mountValue = React.useRef(renderValue).current;
/** Authoritative current value for all imperative work. */
const valueRef = React.useRef(mountValue);
/** Normalized position currently drawn, which during a drag is sub-step. */
const fractionRef = React.useRef(clamp((mountValue - min) / span, 0, 1));
/**
* Frozen copy for the inline style, so SSR and the first paint are correct
* while React never rewrites the property afterwards. A controlled parent
* re-rendering mid-drag would otherwise pull the handle back onto the step
* grid; every later update goes through `paint` instead.
*/
const mountFraction = React.useRef(fractionRef.current).current;
/** Last value handed to `onValueCommit`, so a gesture only commits real changes. */
const commitBaseRef = React.useRef(mountValue);
const sessionRef = React.useRef<DragSession | null>(null);
const frameRef = React.useRef(0);
const pendingXRef = React.useRef(0);
const keyGestureRef = React.useRef(false);
const wheelTimerRef = React.useRef(0);
/** Set by Escape so a trailing blur cannot commit the abandoned draft. */
const editCancelledRef = React.useRef(false);
/** Distinguishes a real exit from edit mode from the initial mount. */
const wasEditingRef = React.useRef(false);
/** Start of the current click sequence, rewound when a double-click opens the editor. */
const clickRef = React.useRef({ time: 0, value: mountValue });
/** Normalized positions where the handle starts to overlap the label or readout. */
const crowdRef = React.useRef({ left: 0.35, right: 0.75 });
const flagsRef = React.useRef({
hover: false,
focus: false,
press: false,
drag: false,
crowded: false,
});
const [editing, setEditing] = React.useState(false);
const [draft, setDraft] = React.useState("");
/* ---------------------------------------------------------------- ticks -- */
const tickFractions = React.useMemo<number[]>(() => {
if (ticks === false) return [];
if (Array.isArray(ticks)) {
return ticks
.map((value) => (value - min) / span)
.filter((fraction) => fraction > 0 && fraction < 1);
}
const stepsInRange = step > 0 ? Math.round(span / step) : 0;
const count =
typeof ticks === "number"
? Math.round(ticks)
: stepsInRange > 1 && stepsInRange <= 12
? stepsInRange
: 10;
if (count < 2) return [];
return Array.from({ length: count - 1 }, (_, index) => (index + 1) / count);
}, [ticks, min, span, step]);
const snapTargets = React.useMemo<number[]>(() => {
if (!snap) return [];
return [0, ...(tickFractions.length ? tickFractions : DECILE_FRACTIONS), 1];
}, [snap, tickFractions]);
const snapFraction = React.useCallback(
(fraction: number) => {
let best = fraction;
let bestDistance = SNAP_RADIUS;
for (const target of snapTargets) {
const distance = Math.abs(target - fraction);
if (distance < bestDistance) {
bestDistance = distance;
best = target;
}
}
return best;
},
[snapTargets],
);
/* ------------------------------------------------------------ painting -- */
/**
* Push the three visual states onto the root as data attributes. They are
* mutually exclusive strings rather than independent booleans so the handle's
* four looks can never fight each other in the cascade.
*/
const writeState = React.useCallback(() => {
const root = rootRef.current;
if (!root) return;
const flags = flagsRef.current;
const active = flags.hover || flags.focus || flags.press || revealed;
root.dataset.active = active ? "true" : "false";
root.dataset.dragging = flags.drag ? "true" : "false";
root.dataset.handle = !active
? "hidden"
: flags.crowded
? "crowded"
: flags.drag
? "dragging"
: "idle";
}, [revealed]);
/**
* Move the fill and the handle. One custom property drives both, as
* compositor-only transforms. The fraction is deliberately independent of the
* step grid so a drag can track the cursor continuously.
*/
const paintFraction = React.useCallback(
(fraction: number) => {
const root = rootRef.current;
if (!root) return;
fractionRef.current = fraction;
root.style.setProperty("--inspector-f", String(fraction));
const crowd = crowdRef.current;
flagsRef.current.crowded = fraction < crowd.left || fraction > crowd.right;
writeState();
},
[writeState],
);
/** Update the readout text and the accessible value on the native input. */
const paintValue = React.useCallback(
(value: number) => {
const text = format(value);
if (readoutRef.current) readoutRef.current.textContent = text;
const input = inputRef.current;
if (input) {
input.value = String(value);
input.setAttribute("aria-valuetext", text);
}
},
[format],
);
/** Write one value to the DOM, handle and readout in agreement. */
const paint = React.useCallback(
(value: number) => {
paintFraction(clamp((value - min) / span, 0, 1));
paintValue(value);
},
[paintFraction, paintValue, min, span],
);
/** Snap, store and broadcast a new value. Returns the value that was applied. */
const apply = React.useCallback(
(raw: number) => {
const value = quantize(raw);
const changed = value !== valueRef.current;
valueRef.current = value;
paint(value);
if (changed) latest.current.onValueChange?.(value);
return value;
},
[quantize, paint],
);
/**
* Drag path. The handle follows the cursor at full resolution while the value
* that is reported and displayed stays on the step grid, so a coarse step
* (say 500) never turns the drag into a sequence of visible jumps. The release
* settles the handle onto the grid position.
*/
const applyFromDrag = React.useCallback(
(fraction: number) => {
paintFraction(fraction);
const value = quantize(min + fraction * span);
if (value === valueRef.current) return;
valueRef.current = value;
paintValue(value);
latest.current.onValueChange?.(value);
},
[paintFraction, paintValue, quantize, min, span],
);
/** Close a gesture, reporting the net change once. */
const endGesture = React.useCallback(() => {
if (valueRef.current === commitBaseRef.current) return;
commitBaseRef.current = valueRef.current;
latest.current.onValueCommit?.(valueRef.current);
}, []);
const nudge = React.useCallback(
(multiplier: number) => {
const increment = step > 0 ? step : span / 100;
apply(valueRef.current + increment * multiplier);
},
[apply, step, span],
);
/* ----------------------------------------------------------- typed edit -- */
const startEditing = () => {
if (disabled || !editable) return;
setDraft(String(valueRef.current));
setEditing(true);
};
/**
* Double-click opens the editor. The number itself is not a hit area — a press
* anywhere, the readout included, moves the value — so the two clicks that led
* here are rewound first.
*/
const handleDoubleClick = () => {
if (disabled || !editable) return;
apply(clickRef.current.value);
startEditing();
};
const commitEdit = () => {
setEditing(false);
// Escape already closed the editor; a blur arriving afterwards must not
// apply the abandoned draft.
if (editCancelledRef.current) {
editCancelledRef.current = false;
return;
}
const parsed = Number.parseFloat(draft.replace(",", "."));
if (!Number.isFinite(parsed)) return;
apply(parsed);
endGesture();
};
const handleEditKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
if (event.key === "Enter") {
event.preventDefault();
commitEdit();
} else if (event.key === "Escape") {
event.preventDefault();
editCancelledRef.current = true;
setEditing(false);
}
};
useIsomorphicLayoutEffect(() => {
if (editing) {
wasEditingRef.current = true;
// focus() before select(): select() alone is not specified to move focus.
editRef.current?.focus({ preventScroll: true });
editRef.current?.select();
return;
}
// Only act on a real exit from edit mode — never on mount, which would
// steal focus on page load.
if (!wasEditingRef.current) return;
wasEditingRef.current = false;
// The readout remounts with the value React last rendered, which is stale in
// uncontrolled mode, so repaint it from the live value.
paint(valueRef.current);
inputRef.current?.focus({ preventScroll: true });
}, [editing, paint]);
/* -------------------------------------------------------------- pointer -- */
/** One value update per frame, no matter how many pointer events arrive. */
const runFrame = React.useCallback(() => {
frameRef.current = 0;
const session = sessionRef.current;
if (!session?.dragging) return;
const x = pendingXRef.current;
const fraction = session.precise
? session.anchorFraction +
(((x - session.anchorX) / session.scale) / session.width) * PRECISION_FACTOR
: (x - session.left) / session.scale / session.width;
// No magnetic snapping here: a drag is continuous, and only `step` limits
// it. Snapping mid-drag would move the value in tick-sized jumps.
applyFromDrag(clamp(fraction, 0, 1));
// Rubber band: how far the cursor has run past the row, eased off.
const past =
x < session.left
? session.left - x
: x > session.right
? x - session.right
: 0;
const overflow = Math.max(0, past - OVERDRAG_DEAD_ZONE);
const pull = OVERDRAG_MAX * Math.sqrt(Math.min(overflow / OVERDRAG_RANGE, 1));
const root = rootRef.current;
root?.style.setProperty("--inspector-pull-w", `${pull}px`);
root?.style.setProperty("--inspector-pull-x", x < session.left ? `${-pull}px` : "0px");
}, [applyFromDrag]);
const handlePointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
// Only the primary button starts a gesture.
if (disabled || event.button !== 0 || !event.isPrimary) return;
const root = rootRef.current;
if (!root) return;
event.preventDefault();
root.setPointerCapture(event.pointerId);
const rect = root.getBoundingClientRect();
const width = root.offsetWidth || rect.width || 1;
sessionRef.current = {
pointerId: event.pointerId,
startX: event.clientX,
startY: event.clientY,
left: rect.left,
right: rect.right,
width,
scale: rect.width / width || 1,
dragging: false,
precise: event.shiftKey,
anchorX: event.clientX,
anchorFraction: fractionRef.current,
};
flagsRef.current.press = true;
writeState();
// Move focus so keyboard, wheel and screen-reader adjustments land here next.
inputRef.current?.focus({ preventScroll: true });
};
const handlePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
const session = sessionRef.current;
if (!session || event.pointerId !== session.pointerId) return;
if (!session.dragging) {
const travel = Math.hypot(event.clientX - session.startX, event.clientY - session.startY);
if (travel <= DRAG_THRESHOLD) return;
session.dragging = true;
session.anchorX = event.clientX;
session.anchorFraction = fractionRef.current;
flagsRef.current.drag = true;
writeState();
}
// Entering or leaving precision mode re-anchors, so the handle never jumps.
if (event.shiftKey !== session.precise) {
session.precise = event.shiftKey;
session.anchorX = event.clientX;
session.anchorFraction = fractionRef.current;
}
pendingXRef.current = event.clientX;
if (!frameRef.current) frameRef.current = requestAnimationFrame(runFrame);
};
const finishGesture = (event: React.PointerEvent<HTMLDivElement>, cancelled: boolean) => {
const session = sessionRef.current;
if (!session || event.pointerId !== session.pointerId) return;
sessionRef.current = null;
if (frameRef.current) {
cancelAnimationFrame(frameRef.current);
frameRef.current = 0;
}
const root = rootRef.current;
flagsRef.current.drag = false;
flagsRef.current.press = false;
if (!cancelled && !session.dragging) {
// A press that never became a drag is a click: Alt resets, otherwise the
// value springs to the release point, magnetically pulled to the nearest
// tick. Aiming is coarse when you tap, so snapping helps there — unlike
// during a drag, where it would fight the cursor.
if (event.altKey) {
apply(resetValue ?? defaultValue ?? min);
} else {
// Remember what the value was before a fresh click sequence, so opening
// the editor with a double-click can undo the clicks that got it there.
const click = clickRef.current;
if (event.timeStamp - click.time > DOUBLE_CLICK_WINDOW) click.value = valueRef.current;
click.time = event.timeStamp;
const raw = clamp((event.clientX - session.left) / session.scale / session.width, 0, 1);
apply(min + (snapTargets.length ? snapFraction(raw) : raw) * span);
}
} else if (session.dragging) {
// Settle the handle from its sub-step drag position onto the grid.
paint(valueRef.current);
}
if (root) {
// Releasing restores the transitions, so the band springs back to rest.
root.style.setProperty("--inspector-pull-w", "0px");
root.style.setProperty("--inspector-pull-x", "0px");
const rect = root.getBoundingClientRect();
flagsRef.current.hover =
event.clientX >= rect.left &&
event.clientX <= rect.right &&
event.clientY >= rect.top &&
event.clientY <= rect.bottom;
}
writeState();
endGesture();
};
/* ------------------------------------------------------------- keyboard -- */
const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
if (disabled) return;
if (event.key === "Enter" && editable) {
event.preventDefault();
startEditing();
return;
}
const increment = (step > 0 ? step : span / 100) * (event.shiftKey ? COARSE_FACTOR : 1);
// Page steps scale with the range, as WAI-ARIA recommends, but never fall
// below a single step on coarse sliders.
const page = Math.max(step > 0 ? step : 0, span / 10);
let next: number | null = null;
switch (event.key) {
case "ArrowRight":
case "ArrowUp":
next = valueRef.current + increment;
break;
case "ArrowLeft":
case "ArrowDown":
next = valueRef.current - increment;
break;
case "PageUp":
next = valueRef.current + page;
break;
case "PageDown":
next = valueRef.current - page;
break;
case "Home":
next = min;
break;
case "End":
next = max;
break;
default:
return;
}
event.preventDefault();
keyGestureRef.current = true;
apply(next);
};
const handleKeyUp = () => {
if (!keyGestureRef.current) return;
keyGestureRef.current = false;
endGesture();
};
/**
* Assistive-technology adjustments (VoiceOver swipes, Windows Narrator) change
* the native input directly instead of firing a key event. The listener is
* attached natively rather than through `onChange` because this component also
* writes `input.value` imperatively, which leaves React's change tracker stale
* and can make it swallow a synthetic change event.
*/
React.useEffect(() => {
const input = inputRef.current;
if (!input || disabled) return;
const onInput = () => {
// Pointer drags and key steps are already handled and write the value
// themselves; only unhandled (assistive) adjustments get here.
if (sessionRef.current || keyGestureRef.current) return;
const next = input.valueAsNumber;
if (!Number.isFinite(next)) return;
apply(next);
endGesture();
};
input.addEventListener("input", onInput);
return () => input.removeEventListener("input", onInput);
}, [apply, endGesture, disabled]);
/* ---------------------------------------------------------------- wheel -- */
React.useEffect(() => {
const root = rootRef.current;
if (!root || !wheel || disabled) return;
// Attached manually because React's onWheel is passive and cannot block the
// page from scrolling. Only a focused row reacts, so plain scrolling past a
// settings panel is never hijacked.
const onWheel = (event: WheelEvent) => {
if (!inputRef.current || document.activeElement !== inputRef.current) return;
const primary =
Math.abs(event.deltaY) >= Math.abs(event.deltaX) ? -event.deltaY : event.deltaX;
const direction = Math.sign(primary);
if (!direction) return;
event.preventDefault();
nudge(direction * (event.shiftKey ? COARSE_FACTOR : 1));
window.clearTimeout(wheelTimerRef.current);
wheelTimerRef.current = window.setTimeout(endGesture, WHEEL_COMMIT_DELAY);
};
root.addEventListener("wheel", onWheel, { passive: false });
return () => {
root.removeEventListener("wheel", onWheel);
window.clearTimeout(wheelTimerRef.current);
};
}, [wheel, disabled, nudge, endGesture]);
/* ---------------------------------------------------------- measurement -- */
useIsomorphicLayoutEffect(() => {
const root = rootRef.current;
if (!root) return;
// Derive the thresholds where the handle would collide with the label or the
// readout from live layout, so padding, icons and size presets all work out
// without hard-coded offsets.
const measure = () => {
const width = root.offsetWidth;
if (!width) return;
const labelEl = labelRef.current;
const readoutEl = readoutRef.current;
const left = labelEl
? (labelEl.offsetLeft + labelEl.offsetWidth + CROWD_BUFFER) / width
: 0.35;
const right = readoutEl ? (readoutEl.offsetLeft - CROWD_BUFFER) / width : 0.75;
const previous = crowdRef.current;
if (previous.left === left && previous.right === right) return;
crowdRef.current = { left, right };
paint(valueRef.current);
};
measure();
const observer = new ResizeObserver(measure);
observer.observe(root);
if (labelRef.current) observer.observe(labelRef.current);
if (readoutRef.current) observer.observe(readoutRef.current);
return () => observer.disconnect();
}, [paint, editing]);
/* ------------------------------------------------- controlled value sync -- */
// `paint` changes identity only when the scale or the formatting does
// (min/max/step/unit), so this repaints the row after such a prop change —
// and gives the first paint its authoritative pass on mount.
useIsomorphicLayoutEffect(() => {
if (sessionRef.current?.dragging) return;
paint(valueRef.current);
}, [paint]);
useIsomorphicLayoutEffect(() => {
if (valueProp === undefined) return; // uncontrolled: the DOM is the source of truth
if (sessionRef.current?.dragging) return; // never fight an in-flight drag
const next = quantize(valueProp);
if (next === valueRef.current) return;
valueRef.current = next;
commitBaseRef.current = next;
paint(next);
}, [valueProp, quantize, paint]);
React.useEffect(() => {
return () => {
if (frameRef.current) cancelAnimationFrame(frameRef.current);
};
}, []);
/* ---------------------------------------------------------------- render -- */
const toneStyle = toneStyles[tone];
return (
// The row is only a pointer surface. The accessible, focusable, form-bound
// slider is the native range input inside it, so the wrapper deliberately
// carries no role of its own.
// biome-ignore lint/a11y/noStaticElementInteractions: pointer surface for the native range input below
// biome-ignore lint/a11y/noNoninteractiveElementInteractions: pointer surface for the native range input below
<div
ref={rootRef}
data-slot="inspector-slider"
data-active={revealed ? "true" : "false"}
data-dragging="false"
data-handle={revealed ? "idle" : "hidden"}
data-disabled={disabled}
className={cn(
"group/inspector-slider relative h-(--inspector-height) touch-none select-none",
"cursor-pointer rounded-(--inspector-radius) data-[dragging=true]:cursor-ew-resize",
"[--inspector-radius:var(--radius-xl)]",
"has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring/50 has-[:focus-visible]:ring-offset-2 has-[:focus-visible]:ring-offset-background",
"data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50",
sizeStyles[size],
className,
)}
style={
{
"--inspector-f": mountFraction,
"--inspector-ease": SPRING_EASE,
} as React.CSSProperties
}
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
onPointerUp={(event) => finishGesture(event, false)}
onPointerCancel={(event) => finishGesture(event, true)}
onDoubleClick={handleDoubleClick}
onPointerEnter={() => {
flagsRef.current.hover = true;
writeState();
}}
onPointerLeave={() => {
flagsRef.current.hover = false;
writeState();
}}
>
<div
data-slot="inspector-slider-track"
className={cn(
"absolute inset-y-0 left-0 overflow-hidden rounded-(--inspector-radius)",
"motion-safe:transition-[width,transform] motion-safe:duration-[420ms] motion-safe:ease-(--inspector-ease)",
"group-data-[dragging=true]/inspector-slider:transition-none",
toneStyle.surface,
)}
style={{
// The rubber band widens and pulls the surface without distorting the
// text inside it. Both vars stay at rest until the cursor overshoots.
width: "calc(100% + var(--inspector-pull-w, 0px))",
transform: "translateX(var(--inspector-pull-x, 0px))",
}}
>
{tickFractions.length > 0 && (
<div
data-slot="inspector-slider-ticks"
aria-hidden="true"
className="pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-200 group-data-[active=true]/inspector-slider:opacity-100"
>
{tickFractions.map((fraction) => (
<span
key={fraction}
className="absolute top-1/2 h-2 w-px -translate-x-1/2 -translate-y-1/2 rounded-full bg-muted-foreground/30"
style={{ left: `${fraction * 100}%` }}
/>
))}
</div>
)}
<div
data-slot="inspector-slider-fill"
aria-hidden="true"
className={cn(
"pointer-events-none absolute inset-0 origin-left",
"motion-safe:transition-[transform,background-color] motion-safe:duration-[420ms] motion-safe:ease-(--inspector-ease)",
"group-data-[dragging=true]/inspector-slider:transition-none",
toneStyle.fill,
)}
style={{ transform: "scaleX(var(--inspector-f))" }}
/>
<div
data-slot="inspector-slider-handle-track"
aria-hidden="true"
className={cn(
"pointer-events-none absolute inset-y-0 left-0 w-full",
"motion-safe:transition-transform motion-safe:duration-[420ms] motion-safe:ease-(--inspector-ease)",
"group-data-[dragging=true]/inspector-slider:transition-none",
)}
style={{
// Percentages inside translateX resolve against this full-width
// positioner, so the handle rides the same custom property as the
// fill while clamp() keeps it clear of the rounded ends.
transform: `translateX(clamp(${HANDLE_INSET}px, calc(var(--inspector-f) * 100% - ${HANDLE_WIDTH / 2}px), calc(100% - ${HANDLE_INSET + HANDLE_WIDTH}px)))`,
}}
>
<div
data-slot="inspector-slider-handle"
className={cn(
"absolute inset-y-2 w-1 rounded-full bg-foreground opacity-50",
"transition-[opacity,transform] duration-200",
"group-data-[handle=hidden]/inspector-slider:scale-x-[0.25] group-data-[handle=hidden]/inspector-slider:opacity-0",
"group-data-[handle=dragging]/inspector-slider:opacity-80",
"group-data-[handle=crowded]/inspector-slider:scale-y-75 group-data-[handle=crowded]/inspector-slider:opacity-10",
)}
/>
</div>
<span
ref={labelRef}
data-slot="inspector-slider-label"
aria-hidden="true"
className={cn(
"pointer-events-none absolute top-1/2 left-(--inspector-pad) flex max-w-[55%] -translate-y-1/2 items-center gap-1.5 text-sm font-medium text-foreground/70",
labelClassName,
)}
>
{Icon && <Icon className="size-4 shrink-0" />}
<span className="truncate">{label}</span>
</span>
{editing ? (
<input
ref={editRef}
type="text"
inputMode="decimal"
value={draft}
onChange={(event) => setDraft(event.target.value)}
onKeyDown={handleEditKeyDown}
onBlur={commitEdit}
aria-label={`${ariaLabel ?? label} value`}
className="absolute top-1/2 right-(--inspector-pad) w-16 -translate-y-1/2 rounded-sm bg-background px-1 text-right font-mono text-sm font-medium tabular-nums text-foreground outline-none ring-2 ring-ring/50"
/>
) : (
<span
ref={readoutRef}
data-slot="inspector-slider-value"
aria-hidden="true"
className={cn(
"pointer-events-none absolute top-1/2 right-(--inspector-pad) -translate-y-1/2",
"font-mono text-sm font-medium tabular-nums transition-colors",
"text-foreground/70 group-data-[active=true]/inspector-slider:text-foreground",
valueClassName,
)}
>
{format(renderValue)}
</span>
)}
{/*
The real slider: a native range input carries the role, the value, the
accessible name, form participation and assistive-technology gestures,
while the visible row above draws the state. Keyboard handling is taken
over so Shift and Page steps behave the same in every browser, so the
step attribute stays open.
*/}
<input
ref={inputRef}
type="range"
className="sr-only"
min={min}
max={max}
step="any"
defaultValue={String(renderValue)}
disabled={disabled}
name={name}
id={id}
aria-label={ariaLabel ?? label}
aria-valuetext={format(renderValue)}
onKeyDown={handleKeyDown}
onKeyUp={handleKeyUp}
onFocus={() => {
flagsRef.current.focus = true;
writeState();
}}
onBlur={() => {
flagsRef.current.focus = false;
writeState();
endGesture();
}}
/>
</div>
</div>
);
}
registry-components/inspector-color/inspector-color.tsx
"use client";
import type { LucideIcon } from "lucide-react";
import * as React from "react";
import { ColorPicker } from "@/components/beste/component/color-picker";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
import { cn } from "@/lib/utils";
/** Surface treatment of the row. Mirrors inspector-slider. */
type Tone = "muted" | "outline" | "ghost";
/** Row height preset. Mirrors inspector-slider. */
type Size = "sm" | "default" | "lg";
/**
* The whole row presses, so each tone answers the hover the way inspector-select's
* trigger does. These are our own classes on our own element, with no `dark:`
* rule underneath to outrank them.
*/
const toneStyles: Record<Tone, string> = {
muted: "border border-transparent bg-muted hover:bg-muted-foreground/15",
outline: "border border-border hover:bg-muted",
ghost: "border border-transparent hover:border-border hover:bg-muted",
};
const sizeStyles: Record<Size, string> = {
sm: "[--inspector-height:--spacing(8)] [--inspector-pad:--spacing(2.5)]",
default: "[--inspector-height:--spacing(9)] [--inspector-pad:--spacing(3)]",
lg: "[--inspector-height:--spacing(11)] [--inspector-pad:--spacing(4)]",
};
/** Checkerboard shown behind a translucent swatch. */
const ALPHA_CHECKER =
"conic-gradient(from 90deg at 50% 50%, color-mix(in srgb, currentColor 20%, transparent) 25%, transparent 0 50%, color-mix(in srgb, currentColor 20%, transparent) 0 75%, transparent 0)";
/** A bare hex, with or without its leading hash. */
const HEX_TEXT = /^#?([0-9a-f]{3,8})$/i;
/** Any of the CSS colour functions the picker understands or the browser renders. */
const COLOR_FUNCTION = /^(rgba?|oklch|hsla?|oklab|lab|lch|color)\(/i;
/** Accepts hex, `rgb()`/`rgba()` and `oklch()`; anything else keeps the swatch empty. */
function isRenderableColor(value: string | undefined): boolean {
if (!value) return false;
const candidate = value.trim();
return HEX_TEXT.test(candidate) || COLOR_FUNCTION.test(candidate);
}
interface InspectorColorProps {
/** Label rendered on the left, inside the row. */
label: string;
/** Optional leading icon shown before the label. */
icon?: LucideIcon;
/** Controlled colour. Pair it with `onValueChange`. */
value?: string;
/** Initial colour in uncontrolled mode. */
defaultValue?: string;
/** Fires on every adjustment, including each frame of a drag in the picker. */
onValueChange?: (value: string) => void;
/**
* Fires once an adjustment is finished — a drag release, a committed edit, a
* swatch click. Use it for work too expensive to run per frame.
*/
onValueCommit?: (value: string) => void;
/** Fires when the picker opens or closes. */
onOpenChange?: (open: boolean) => void;
/**
* Notation written back through the callbacks.
* @defaultValue "hex" */
format?: "hex" | "oklch" | "rgb";
/** Carry an alpha channel, and show its rail in the picker. */
alpha?: boolean;
/** Preset colors offered inside the picker. */
swatches?: string[];
/** Block interaction and dim the row. */
disabled?: boolean;
/**
* Surface treatment: filled (default), hairline outline, or bare until hover.
* @defaultValue "muted" */
tone?: Tone;
/**
* Row height preset.
* @defaultValue "default" */
size?: Size;
className?: string;
/** Accessible name. Falls back to `label`. */
"aria-label"?: string;
}
// No `swatches`: presets are opt-in, so the picker opens without a swatch row.
export const inspectorColorDemo: InspectorColorProps = {
label: "Color",
className: "w-72",
defaultValue: "#171717",
};
export function InspectorColor({
label,
icon: Icon,
value: valueProp,
defaultValue,
onValueChange,
onValueCommit,
onOpenChange,
format = "hex",
alpha = false,
swatches,
disabled = false,
tone = "muted",
size = "default",
className,
"aria-label": ariaLabel,
}: InspectorColorProps) {
const [internalValue, setInternalValue] = React.useState(defaultValue ?? "#000000");
const value = valueProp ?? internalValue;
const commit = React.useCallback(
(next: string, complete: boolean) => {
if (valueProp === undefined) setInternalValue(next);
onValueChange?.(next);
if (complete) onValueCommit?.(next);
},
[valueProp, onValueChange, onValueCommit]
);
const swatchColor = isRenderableColor(value) ? value : "transparent";
return (
<Popover onOpenChange={onOpenChange}>
{/*
The whole row is the trigger. With the value read-only there is nothing
else in the row to press, so a 20px circle would be a needlessly small
target — and the row can say "Color, #171717" as its own accessible name
instead of carrying a separate label for the swatch. Nothing interactive
is nested inside, which is what makes a button legal here.
*/}
<PopoverTrigger asChild>
<button
type="button"
disabled={disabled}
aria-label={ariaLabel}
data-slot="inspector-color"
data-disabled={disabled}
className={cn(
"group/inspector-color relative flex w-full cursor-pointer items-center gap-2 text-left select-none",
"h-(--inspector-height) rounded-(--inspector-radius) px-(--inspector-pad)",
"[--inspector-radius:var(--radius-xl)] transition-colors",
"outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background",
"data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50",
sizeStyles[size],
toneStyles[tone],
className
)}
>
<span
data-slot="inspector-color-label"
className="flex min-w-0 items-center gap-1.5 text-sm font-medium text-foreground/70"
>
{Icon ? <Icon className="size-4 shrink-0" /> : null}
<span className="truncate">{label}</span>
</span>
{/*
Read-only on purpose: a colour is edited in the picker, where a bad
value can be seen as well as typed. A field here would also mean two
places to keep in step.
*/}
<span
data-slot="inspector-color-value"
className="ml-auto min-w-0 truncate font-mono text-sm font-medium text-foreground"
>
{value}
</span>
<span
aria-hidden="true"
data-slot="inspector-color-swatch"
className={cn(
"relative size-5 shrink-0 rounded-full border border-border",
"transition-transform group-hover/inspector-color:scale-110"
)}
>
{alpha ? (
<span
className="absolute inset-0 rounded-full text-foreground"
style={{ backgroundImage: ALPHA_CHECKER, backgroundSize: "6px 6px" }}
/>
) : null}
<span
className="absolute inset-0 rounded-full"
style={{ backgroundColor: swatchColor }}
/>
</span>
</button>
</PopoverTrigger>
<PopoverContent align="end" side="bottom" sideOffset={8} className="w-auto p-0">
<ColorPicker
color={value}
format={format}
alpha={alpha}
swatches={swatches}
onChange={(next) => commit(next, false)}
onChangeComplete={(next) => commit(next, true)}
/>
</PopoverContent>
</Popover>
);
}
registry-components/color-picker/color-picker.tsx
"use client";
import { CheckIcon, PipetteIcon } from "lucide-react";
import * as React from "react";
import { InspectorSlider } from "@/components/beste/component/inspector-slider";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
import { cn } from "@/lib/utils";
/** Notation the callbacks emit. Input is always parsed from any of them. */
type ColorFormat = "hex" | "oklch" | "rgb";
/** The working model. OKLCH is perceptual, so every control moves predictably. */
interface OklchColor {
/** Lightness, 0 to 1. */
l: number;
/** Chroma, 0 to ~0.4 for sRGB. */
c: number;
/** Hue angle in degrees, 0 to 360. */
h: number;
/** Alpha, 0 to 1. */
a: number;
}
/* -------------------------------------------------------------------------- */
/* Tuning */
/* -------------------------------------------------------------------------- */
/** Chroma ceiling for the slider. sRGB tops out near 0.32, P3 a little higher. */
const CHROMA_MAX = 0.4;
/** Backing resolution of the lightness/chroma plane; CSS scales it up smoothly. */
const PLANE_WIDTH = 96;
const PLANE_HEIGHT = 64;
/** Tolerance for calling a converted channel in-gamut. */
const GAMUT_EPSILON = 0.0005;
/** Keyboard step on the plane. */
const PLANE_KEY_STEP = 0.01;
const PLANE_KEY_STEP_COARSE = 0.1;
const FALLBACK_COLOR: OklchColor = { l: 0.5, c: 0, h: 0, a: 1 };
/** Hue rail: one stop per 30 degrees, at a mid lightness and chroma. */
const HUE_RAIL = `linear-gradient(to right, ${Array.from(
{ length: 13 },
(_, index) => `oklch(0.72 0.17 ${index * 30})`
).join(", ")})`;
/** Checkerboard behind the alpha rail, drawn with one conic gradient. */
const ALPHA_CHECKER =
"conic-gradient(from 90deg at 50% 50%, color-mix(in srgb, currentColor 12%, transparent) 25%, transparent 0 50%, color-mix(in srgb, currentColor 12%, transparent) 0 75%, transparent 0)";
/*
* A row is a plain inspector-slider until it is hovered, and its ramp only
* appears then. Everything below is scoped to that hover, and all three parts
* have to move together: uncovering the gradient means dropping the row's own
* surface and fill, which would otherwise sit on top of it, and the label and the
* value have to go white with a halo for the moment they are over a ramp that can
* run from black to white. `group-hover/rail` is what ties them to the wrapper.
*
* The value restates itself under `group-data-[active=true]` because hovering
* also engages the row, which brightens the readout to `text-foreground` — a rule
* specific enough to win unless the override matches it.
*/
const RAIL_SURFACE =
"group-hover/rail:[&_[data-slot=inspector-slider-track]]:bg-transparent group-hover/rail:[&_[data-slot=inspector-slider-fill]]:bg-transparent";
const RAIL_LABEL = "group-hover/rail:text-white group-hover/rail:[text-shadow:0_1px_3px_#000c]";
const RAIL_VALUE =
"group-hover/rail:text-white group-hover/rail:group-data-[active=true]/inspector-slider:text-white group-hover/rail:[text-shadow:0_1px_3px_#000c]";
/* -------------------------------------------------------------------------- */
/* Color maths — sRGB <-> OKLab/OKLCH, using Björn Ottosson's matrices */
/* -------------------------------------------------------------------------- */
const useIsomorphicLayoutEffect =
typeof window === "undefined" ? React.useEffect : React.useLayoutEffect;
function clamp(value: number, lo: number, hi: number) {
return Math.min(hi, Math.max(lo, value));
}
function srgbToLinear(channel: number) {
return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
}
function linearToSrgb(channel: number) {
return channel <= 0.0031308 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;
}
/** Linear sRGB in 0..1 to OKLCH. */
function linearRgbToOklch(r: number, g: number, b: number): OklchColor {
const long = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
const medium = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
const short = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
const lightness = 0.2104542553 * long + 0.793617785 * medium - 0.0040720468 * short;
const a = 1.9779984951 * long - 2.428592205 * medium + 0.4505937099 * short;
const b2 = 0.0259040371 * long + 0.7827717662 * medium - 0.808675766 * short;
const chroma = Math.hypot(a, b2);
const hue = chroma < 1e-6 ? 0 : ((Math.atan2(b2, a) * 180) / Math.PI + 360) % 360;
return { l: clamp(lightness, 0, 1), c: chroma, h: hue, a: 1 };
}
/** OKLCH to linear sRGB. Channels may fall outside 0..1 when out of gamut. */
function oklchToLinearRgb({ l, c, h }: OklchColor) {
const hueRadians = (h * Math.PI) / 180;
const a = c * Math.cos(hueRadians);
const b = c * Math.sin(hueRadians);
const long = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
const medium = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
const short = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
return {
r: 4.0767416621 * long - 3.3077115913 * medium + 0.2309699292 * short,
g: -1.2684380046 * long + 2.6097574011 * medium - 0.3413193965 * short,
b: -0.0041960863 * long - 0.7034186147 * medium + 1.707614701 * short,
};
}
/** 0..255 sRGB plus whether the colour actually fits in the sRGB gamut. */
function oklchToRgb(color: OklchColor) {
const linear = oklchToLinearRgb(color);
const inGamut =
linear.r >= -GAMUT_EPSILON &&
linear.r <= 1 + GAMUT_EPSILON &&
linear.g >= -GAMUT_EPSILON &&
linear.g <= 1 + GAMUT_EPSILON &&
linear.b >= -GAMUT_EPSILON &&
linear.b <= 1 + GAMUT_EPSILON;
return {
r: Math.round(clamp(linearToSrgb(clamp(linear.r, 0, 1)), 0, 1) * 255),
g: Math.round(clamp(linearToSrgb(clamp(linear.g, 0, 1)), 0, 1) * 255),
b: Math.round(clamp(linearToSrgb(clamp(linear.b, 0, 1)), 0, 1) * 255),
inGamut,
};
}
/**
* Highest chroma that still fits in sRGB at this lightness and hue. The binary
* search keeps the last in-gamut value, so the result is always reachable.
*
* The plane's horizontal axis is this maximum rather than an absolute chroma:
* drawing absolute chroma leaves most of the plane out of gamut, as a large
* unusable wedge whose stair-stepped edge reads as a rendering fault. Scaling
* each row to its own limit fills the plane and means every pixel the reader can
* aim at is a colour sRGB can actually show.
*/
function maxChromaAt(l: number, h: number) {
let low = 0;
let high = 0.5;
for (let step = 0; step < 16; step++) {
const mid = (low + high) / 2;
if (oklchToRgb({ l, c: mid, h, a: 1 }).inGamut) low = mid;
else high = mid;
}
return low;
}
/** Chroma for a point on the plane, given how far across the row it sits. */
function chromaFromPlane(relative: number, l: number, h: number) {
return clamp(relative, 0, 1) * maxChromaAt(l, h);
}
/** Where on its row a chroma sits, 0 at grey and 1 at the gamut edge. */
function planePositionOf(c: number, l: number, h: number) {
const rowMax = maxChromaAt(l, h);
return rowMax < 1e-4 ? 0 : clamp(c / rowMax, 0, 1);
}
/* ------------------------------------------------------------ parse/format -- */
function trimNumber(value: number, decimals: number) {
return String(Number(value.toFixed(decimals)));
}
function toHexChannel(value: number) {
return value.toString(16).padStart(2, "0");
}
function formatColor(color: OklchColor, format: ColorFormat, withAlpha: boolean): string {
const alpha = clamp(color.a, 0, 1);
if (format === "oklch") {
const base = `${trimNumber(color.l, 4)} ${trimNumber(color.c, 4)} ${trimNumber(color.h, 2)}`;
return withAlpha && alpha < 1 ? `oklch(${base} / ${trimNumber(alpha, 3)})` : `oklch(${base})`;
}
const { r, g, b } = oklchToRgb(color);
if (format === "rgb") {
return withAlpha && alpha < 1
? `rgba(${r}, ${g}, ${b}, ${trimNumber(alpha, 3)})`
: `rgb(${r}, ${g}, ${b})`;
}
const hex = `#${toHexChannel(r)}${toHexChannel(g)}${toHexChannel(b)}`;
return withAlpha && alpha < 1 ? `${hex}${toHexChannel(Math.round(alpha * 255))}` : hex;
}
/** Parse hex (3/4/6/8 digits), `rgb()`/`rgba()` or `oklch()` into the model. */
function parseColor(input: string | undefined): OklchColor | null {
if (!input) return null;
const value = input.trim().toLowerCase();
if (!value) return null;
const hex = /^#?([0-9a-f]{3,8})$/.exec(value);
if (hex?.[1]) {
const digits = hex[1];
const expand = (pair: string) => Number.parseInt(pair, 16) / 255;
let parts: string[] | null = null;
if (digits.length === 3 || digits.length === 4) {
parts = digits.split("").map((digit) => digit + digit);
} else if (digits.length === 6 || digits.length === 8) {
parts = digits.match(/.{2}/g);
}
if (!parts) return null;
const [r, g, b, a] = parts;
if (r === undefined || g === undefined || b === undefined) return null;
const oklch = linearRgbToOklch(
srgbToLinear(expand(r)),
srgbToLinear(expand(g)),
srgbToLinear(expand(b))
);
return { ...oklch, a: a === undefined ? 1 : expand(a) };
}
const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(
value
);
if (rgb?.[1] && rgb[2] && rgb[3]) {
const channel = (part: string) => srgbToLinear(clamp(Number.parseFloat(part) / 255, 0, 1));
const oklch = linearRgbToOklch(channel(rgb[1]), channel(rgb[2]), channel(rgb[3]));
return { ...oklch, a: parseAlpha(rgb[4]) };
}
const oklch =
/^oklch\(\s*([\d.]+%?)\s+([\d.]+%?)\s+([\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+%?))?\s*\)$/.exec(
value
);
if (oklch?.[1] && oklch[2] && oklch[3]) {
const lightness = oklch[1].endsWith("%")
? Number.parseFloat(oklch[1]) / 100
: Number.parseFloat(oklch[1]);
const chroma = oklch[2].endsWith("%")
? (Number.parseFloat(oklch[2]) / 100) * CHROMA_MAX
: Number.parseFloat(oklch[2]);
const hue = Number.parseFloat(oklch[3]);
if (!Number.isFinite(lightness) || !Number.isFinite(chroma) || !Number.isFinite(hue)) {
return null;
}
return {
l: clamp(lightness, 0, 1),
c: clamp(chroma, 0, 0.5),
h: ((hue % 360) + 360) % 360,
a: parseAlpha(oklch[4]),
};
}
return null;
}
function parseAlpha(raw: string | undefined) {
if (raw === undefined) return 1;
const value = raw.endsWith("%") ? Number.parseFloat(raw) / 100 : Number.parseFloat(raw);
return Number.isFinite(value) ? clamp(value, 0, 1) : 1;
}
/** One row: its ramp, revealed on hover, under the slider that rides on it. */
function Rail({
gradient,
checker = false,
children,
}: {
gradient: string;
checker?: boolean;
children: React.ReactNode;
}) {
return (
<div className="group/rail relative">
<div
aria-hidden="true"
className="pointer-events-none absolute inset-0 rounded-(--inspector-radius) opacity-0 transition-opacity duration-200 group-hover/rail:opacity-100"
>
{checker ? (
// `currentColor` in the checker resolves against this class, so the
// squares stay neutral instead of picking up the chosen colour.
<div
className="absolute inset-0 rounded-(--inspector-radius) text-foreground/70"
style={{ backgroundImage: ALPHA_CHECKER, backgroundSize: "8px 8px" }}
/>
) : null}
<div
className="absolute inset-0 rounded-(--inspector-radius)"
style={{ backgroundImage: gradient }}
/>
</div>
{children}
</div>
);
}
/** CSS colour for previews. Always renders, even when out of the sRGB gamut. */
function toCssColor(color: OklchColor) {
const { r, g, b } = oklchToRgb(color);
return color.a < 1 ? `rgba(${r}, ${g}, ${b}, ${clamp(color.a, 0, 1)})` : `rgb(${r}, ${g}, ${b})`;
}
/* -------------------------------------------------------------------------- */
/* Props */
/* -------------------------------------------------------------------------- */
interface ColorPickerProps {
/** Current colour. Hex, `rgb()`/`rgba()` and `oklch()` are all understood. */
color?: string;
/** Fires on every adjustment, in `format`. */
onChange?: (color: string) => void;
/**
* Fires once an adjustment is finished — a drag release, a committed edit, a
* swatch click. Use it for work too expensive to run per frame.
*/
onChangeComplete?: (color: string) => void;
/**
* Notation the callbacks emit.
* @defaultValue "hex" */
format?: ColorFormat;
/** Show the alpha row and carry an alpha channel through `format`. */
alpha?: boolean;
/**
* Offer the RGB/OKLCH tabs. The OKLCH one adds lightness and chroma rows for
* precise control and writes the value as `oklch(...)`; the choice only affects
* what is shown and typed, never what `format` emits. Turn it off for a compact
* picker: plane, hue and the field.
* @defaultValue true */
oklch?: boolean;
/** Preset colors offered under the picker, in any supported notation. */
swatches?: string[];
/** Hide the text field that accepts and displays the value. */
hideInput?: boolean;
className?: string;
/** Accessible name for the lightness/chroma plane. */
"aria-label"?: string;
}
// Swatches are deliberately absent: presets are opt-in, and the default picker
// is the plane, the rows and the field.
export const colorPickerDemo: ColorPickerProps = {
color: "#6366f1",
};
/* -------------------------------------------------------------------------- */
/* Component */
/* -------------------------------------------------------------------------- */
export function ColorPicker({
color: colorProp,
onChange,
onChangeComplete,
format = "hex",
alpha = false,
oklch = true,
swatches,
hideInput = false,
className,
"aria-label": ariaLabel,
}: ColorPickerProps) {
const [color, setColor] = React.useState<OklchColor>(
() => parseColor(colorProp) ?? FALLBACK_COLOR
);
const [draft, setDraft] = React.useState<string | null>(null);
/** Which notation the field shows and the numeric rows follow. */
const [notation, setNotation] = React.useState<"rgb" | "oklch">(
format === "oklch" ? "oklch" : "rgb"
);
const canvasRef = React.useRef<HTMLCanvasElement>(null);
const planeRef = React.useRef<HTMLDivElement>(null);
const colorRef = React.useRef(color);
const draggingRef = React.useRef(false);
const frameRef = React.useRef(0);
const pendingRef = React.useRef({ x: 0, y: 0 });
colorRef.current = color;
const latest = React.useRef({ onChange, onChangeComplete, format, alpha });
useIsomorphicLayoutEffect(() => {
latest.current = { onChange, onChangeComplete, format, alpha };
});
const emit = React.useCallback((next: OklchColor, complete = false) => {
colorRef.current = next;
setColor(next);
const {
onChange: change,
onChangeComplete: done,
format: fmt,
alpha: withAlpha,
} = latest.current;
const value = formatColor(next, fmt, withAlpha);
change?.(value);
if (complete) done?.(value);
}, []);
/* ------------------------------------------------- incoming prop changes -- */
useIsomorphicLayoutEffect(() => {
if (colorProp === undefined || draggingRef.current) return;
const parsed = parseColor(colorProp);
if (!parsed) return;
// Compare in the emitted notation: a hex prop cannot round-trip every OKLCH
// value, so comparing components would fight the consumer every render.
const { format: fmt, alpha: withAlpha } = latest.current;
if (formatColor(parsed, fmt, withAlpha) === formatColor(colorRef.current, fmt, withAlpha)) {
return;
}
colorRef.current = parsed;
setColor(parsed);
}, [colorProp]);
/* ------------------------------------------------------- plane rendering -- */
useIsomorphicLayoutEffect(() => {
const canvas = canvasRef.current;
const context = canvas?.getContext("2d");
if (!canvas || !context) return;
const image = context.createImageData(PLANE_WIDTH, PLANE_HEIGHT);
const pixels = image.data;
for (let y = 0; y < PLANE_HEIGHT; y++) {
const lightness = 1 - y / (PLANE_HEIGHT - 1);
// One gamut probe per row, then the row is a straight ramp from grey to
// that row's most saturated colour, so every pixel is in gamut.
const rowMax = maxChromaAt(lightness, color.h);
for (let x = 0; x < PLANE_WIDTH; x++) {
const chroma = (x / (PLANE_WIDTH - 1)) * rowMax;
const rgb = oklchToRgb({ l: lightness, c: chroma, h: color.h, a: 1 });
const offset = (y * PLANE_WIDTH + x) * 4;
pixels[offset] = rgb.r;
pixels[offset + 1] = rgb.g;
pixels[offset + 2] = rgb.b;
pixels[offset + 3] = 255;
}
}
context.putImageData(image, 0, 0);
}, [color.h]);
/* ------------------------------------------------------------ plane drag -- */
const applyFromPlane = React.useCallback(() => {
frameRef.current = 0;
const plane = planeRef.current;
if (!plane) return;
const rect = plane.getBoundingClientRect();
if (!rect.width || !rect.height) return;
const { x, y } = pendingRef.current;
const nextL = clamp(1 - (y - rect.top) / rect.height, 0, 1);
const relative = (x - rect.left) / rect.width;
emit({
...colorRef.current,
l: nextL,
c: chromaFromPlane(relative, nextL, colorRef.current.h),
});
}, [emit]);
const handlePlanePointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
if (event.button !== 0 || !event.isPrimary) return;
event.preventDefault();
planeRef.current?.setPointerCapture(event.pointerId);
draggingRef.current = true;
planeRef.current?.focus({ preventScroll: true });
pendingRef.current = { x: event.clientX, y: event.clientY };
applyFromPlane();
};
const handlePlanePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
if (!draggingRef.current) return;
pendingRef.current = { x: event.clientX, y: event.clientY };
// One update per frame, however many pointer events arrive.
if (!frameRef.current) frameRef.current = requestAnimationFrame(applyFromPlane);
};
const handlePlanePointerUp = () => {
if (!draggingRef.current) return;
draggingRef.current = false;
if (frameRef.current) {
cancelAnimationFrame(frameRef.current);
frameRef.current = 0;
}
emit(colorRef.current, true);
};
const handlePlaneKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
const step = event.shiftKey ? PLANE_KEY_STEP_COARSE : PLANE_KEY_STEP;
const current = colorRef.current;
const relative = planePositionOf(current.c, current.l, current.h);
let next: OklchColor | null = null;
switch (event.key) {
case "ArrowUp": {
// Keep the same distance across the row while lightness moves, so the
// colour stays as saturated as it was.
const l = clamp(current.l + step, 0, 1);
next = { ...current, l, c: chromaFromPlane(relative, l, current.h) };
break;
}
case "ArrowDown": {
const l = clamp(current.l - step, 0, 1);
next = { ...current, l, c: chromaFromPlane(relative, l, current.h) };
break;
}
case "ArrowRight":
next = { ...current, c: chromaFromPlane(relative + step, current.l, current.h) };
break;
case "ArrowLeft":
next = { ...current, c: chromaFromPlane(relative - step, current.l, current.h) };
break;
default:
return;
}
event.preventDefault();
emit(next, true);
};
React.useEffect(() => {
return () => {
if (frameRef.current) cancelAnimationFrame(frameRef.current);
};
}, []);
/* ----------------------------------------------------------- text field -- */
/**
* The tabs choose how the value is written and typed, never what the callbacks
* emit — that stays the consumer's `format`, so switching tabs cannot start
* handing a component that asked for hex an `oklch()` string instead.
*/
const fieldFormat: ColorFormat =
notation === "oklch" ? "oklch" : format === "oklch" ? "hex" : format;
const displayValue = formatColor(color, fieldFormat, alpha);
const draftIsValid = draft === null || parseColor(draft) !== null;
const handleDraftChange = (raw: string) => {
setDraft(raw);
const parsed = parseColor(raw);
if (parsed) emit(parsed);
};
const commitDraft = () => {
const parsed = draft === null ? null : parseColor(draft);
setDraft(null);
if (parsed) emit(parsed, true);
};
/* ----------------------------------------------------------- eyedropper -- */
const [hasEyeDropper, setHasEyeDropper] = React.useState(false);
useIsomorphicLayoutEffect(() => {
setHasEyeDropper(typeof window !== "undefined" && "EyeDropper" in window);
}, []);
const pickFromScreen = async () => {
const Picker = (
window as unknown as {
EyeDropper?: new () => { open: () => Promise<{ sRGBHex: string }> };
}
).EyeDropper;
if (!Picker) return;
try {
const result = await new Picker().open();
const parsed = parseColor(result.sRGBHex);
if (parsed) emit({ ...parsed, a: colorRef.current.a }, true);
} catch {
// The reader dismissed the eyedropper; nothing to do.
}
};
/* --------------------------------------------------------------- render -- */
const cssColor = toCssColor(color);
const puckX = planePositionOf(color.c, color.l, color.h);
const puckY = 1 - color.l;
const outOfGamut = !oklchToRgb(color).inGamut;
// Hue and alpha belong to both tabs, and the field only changes notation, so
// they are built once here and placed in each tab. Only one tab is mounted at
// a time, so no element is ever rendered twice.
const hueRow = (
<Rail gradient={HUE_RAIL}>
<InspectorSlider
label="Hue"
className={RAIL_SURFACE}
labelClassName={RAIL_LABEL}
valueClassName={RAIL_VALUE}
size="sm"
min={0}
max={360}
step={1}
ticks={false}
value={color.h}
onValueChange={(value) => emit({ ...colorRef.current, h: value })}
onValueCommit={() => emit(colorRef.current, true)}
formatValue={(value) => `${Math.round(value)}°`}
/>
</Rail>
);
const alphaRow = alpha ? (
<Rail
checker
gradient={`linear-gradient(to right, transparent, ${toCssColor({ ...color, a: 1 })})`}
>
<InspectorSlider
label="Alpha"
className={RAIL_SURFACE}
labelClassName={RAIL_LABEL}
valueClassName={RAIL_VALUE}
size="sm"
min={0}
max={1}
step={0.01}
ticks={false}
value={color.a}
onValueChange={(value) => emit({ ...colorRef.current, a: value })}
onValueCommit={() => emit(colorRef.current, true)}
formatValue={(value) => `${Math.round(value * 100)}%`}
/>
</Rail>
) : null;
const field = hideInput ? null : (
<div data-slot="color-picker-field" className="flex items-center gap-1.5 pt-1">
{/*
The plane can no longer land out of gamut, so this only marks a value the
numeric rows or a typed value pushed past sRGB. It stays a quiet hint
rather than an error state.
*/}
<span
aria-hidden="true"
data-out-of-gamut={outOfGamut}
title={outOfGamut ? "Outside the sRGB gamut — shown clamped" : undefined}
className="size-8 shrink-0 rounded-md border border-border data-[out-of-gamut=true]:ring-1 data-[out-of-gamut=true]:ring-muted-foreground/50"
style={{ backgroundColor: cssColor }}
/>
<Input
value={draft ?? displayValue}
spellCheck={false}
autoComplete="off"
aria-label="Color value"
aria-invalid={!draftIsValid}
onChange={(event) => handleDraftChange(event.target.value)}
onBlur={commitDraft}
onKeyDown={(event) => {
if (event.key === "Enter") {
event.preventDefault();
commitDraft();
} else if (event.key === "Escape") {
event.preventDefault();
setDraft(null);
}
}}
className="h-8 min-w-0 flex-1 px-2 font-mono text-sm"
/>
{hasEyeDropper ? (
<Button
type="button"
variant="outline"
size="icon"
aria-label="Pick a colour from the screen"
onClick={pickFromScreen}
className="size-8 shrink-0 cursor-pointer"
>
<PipetteIcon className="size-4" />
</Button>
) : null}
</div>
);
return (
// The click guard keeps the picker usable inside a card, a menu item or any
// other ancestor that acts on clicks of its own.
// biome-ignore lint/a11y/noStaticElementInteractions: containment guard, not a control
// biome-ignore lint/a11y/noNoninteractiveElementInteractions: containment guard, not a control
<div
data-slot="color-picker"
onClick={(event) => event.stopPropagation()}
className={cn(
// `max-w-full` lets the panel sit inside a narrower popover than its own
// intrinsic width without overflowing it.
"flex w-64 max-w-full flex-col gap-2 p-3 [--inspector-radius:var(--radius-xl)]",
className
)}
>
{/*
The plane is a convenience: the lightness, chroma and hue rows below are
real range inputs and remain the accessible path, which is why this
surface carries no widget role of its own.
*/}
{/* biome-ignore lint/a11y/noStaticElementInteractions: pointer surface for the sliders below */}
{/* biome-ignore lint/a11y/noNoninteractiveElementInteractions: pointer surface for the sliders below */}
<div
ref={planeRef}
data-slot="color-picker-plane"
tabIndex={0}
aria-label={ariaLabel ?? "Lightness and chroma"}
className={cn(
"relative h-36 w-full cursor-crosshair touch-none overflow-hidden rounded-(--inspector-radius)",
"bg-muted outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background"
)}
onPointerDown={handlePlanePointerDown}
onPointerMove={handlePlanePointerMove}
onPointerUp={handlePlanePointerUp}
onPointerCancel={handlePlanePointerUp}
onKeyDown={handlePlaneKeyDown}
>
<canvas
ref={canvasRef}
width={PLANE_WIDTH}
height={PLANE_HEIGHT}
aria-hidden="true"
className="pointer-events-none absolute inset-0 size-full"
/>
<div
aria-hidden="true"
className="pointer-events-none absolute inset-0"
style={{ transform: `translate(${puckX * 100}%, ${puckY * 100}%)` }}
>
<div
data-slot="color-picker-puck"
className="absolute size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-md ring-1 ring-black/20"
style={{ backgroundColor: cssColor }}
/>
</div>
</div>
{oklch ? (
<Tabs
value={notation}
onValueChange={(value) => setNotation(value === "oklch" ? "oklch" : "rgb")}
>
<TabsList className="w-full">
<TabsTrigger value="rgb" className="flex-1 cursor-pointer">
RGB
</TabsTrigger>
<TabsTrigger value="oklch" className="flex-1 cursor-pointer">
OKLCH
</TabsTrigger>
</TabsList>
{/*
Hue drives the plane, so it belongs to both tabs; lightness and chroma
repeat the plane's own axes and are only worth the space when someone
has asked for numbers, which is what choosing OKLCH says.
*/}
<TabsContent value="rgb" className="flex flex-col gap-1">
{hueRow}
{alphaRow}
{field}
</TabsContent>
<TabsContent value="oklch" className="flex flex-col gap-1">
<Rail
gradient={`linear-gradient(to right, oklch(0 ${color.c} ${color.h}), oklch(1 ${color.c} ${color.h}))`}
>
<InspectorSlider
label="Lightness"
className={RAIL_SURFACE}
labelClassName={RAIL_LABEL}
valueClassName={RAIL_VALUE}
size="sm"
min={0}
max={1}
step={0.005}
ticks={false}
value={color.l}
onValueChange={(value) => emit({ ...colorRef.current, l: value })}
onValueCommit={() => emit(colorRef.current, true)}
formatValue={(value) => value.toFixed(3)}
/>
</Rail>
<Rail
gradient={`linear-gradient(to right, oklch(${color.l} 0 ${color.h}), oklch(${color.l} ${CHROMA_MAX} ${color.h}))`}
>
<InspectorSlider
label="Chroma"
className={RAIL_SURFACE}
labelClassName={RAIL_LABEL}
valueClassName={RAIL_VALUE}
size="sm"
min={0}
max={CHROMA_MAX}
step={0.005}
ticks={false}
value={color.c}
onValueChange={(value) => emit({ ...colorRef.current, c: value })}
onValueCommit={() => emit(colorRef.current, true)}
formatValue={(value) => value.toFixed(3)}
/>
</Rail>
{hueRow}
{alphaRow}
{field}
</TabsContent>
</Tabs>
) : (
<div className="flex flex-col gap-1">
{hueRow}
{alphaRow}
{field}
</div>
)}
{swatches?.length ? (
// Eight to a row, each cell taking an equal share of the width, so any
// number of presets stays on a tidy grid instead of wrapping ragged.
<div data-slot="color-picker-swatches" className="grid grid-cols-8 gap-1.5 pt-1">
{swatches.map((swatch) => {
const parsed = parseColor(swatch);
const isActive = parsed
? formatColor(parsed, "hex", false) === formatColor(color, "hex", false)
: false;
return (
<button
key={swatch}
type="button"
aria-label={swatch}
aria-pressed={isActive}
onClick={() => {
if (parsed) emit(parsed, true);
}}
className="flex aspect-square w-full cursor-pointer items-center justify-center rounded-full border border-border transition-transform hover:scale-110"
style={{ backgroundColor: parsed ? toCssColor(parsed) : swatch }}
>
{isActive ? (
<CheckIcon className="size-3.5 text-white mix-blend-difference" />
) : null}
</button>
);
})}
</div>
) : null}
</div>
);
}