Introduction

Colorshot is the color picker inside Orshot Studio, open sourced. It takes any CSS color or gradient string and gives one back, so it fits whatever your app already stores. It never throws on input it cannot read, and the parts of a value you did not edit come back exactly as written.

• Solid colors with hue, saturation, alpha, eyedropper and hex / rgb / hsl / oklch input
• Linear, radial, conic and repeating gradients with draggable stops, an angle dial and a center pad
• Paste any CSS color or gradient with Cmd/Ctrl+V, copy with Cmd/Ctrl+C
• Your own swatch groups: brand, saved, recent, with search, add, remove, reorder and rename
• A ready-made ColorPicker, a ColorField that opens it in a popover, or headless parts to build your own layout
• Keyboard, screen reader, touch and two-finger trackpad support
• React and Vue from one framework-free core, themed with CSS variables

Install

npm i @orshot/colorshot

Getting started

"use client";

import { useState } from "react";
import { ColorPicker } from "@orshot/colorshot/react";
import "@orshot/colorshot/styles.css";

export function FillPicker() {
  const [fill, setFill] = useState("linear-gradient(135deg, #3E5CEB 0%, #22C55E 100%)");

  return (
    <ColorPicker
      value={fill}
      onChange={setFill} // every frame while dragging
      onChangeComplete={(value) => save(value)} // once, when the change is done
    />
  );
}

Vue:

<script setup>
import { ref } from "vue";
import { ColorPicker } from "@orshot/colorshot/vue";
import "@orshot/colorshot/styles.css";

const fill = ref("#3E5CEB");
</script>

<template>
  <ColorPicker v-model="fill" @change-complete="save" />
</template>

Examples

Live versions of every example: https://orshot.com/open-source/colorshot#linear

Linear, radial or conic gradient only

One mode hides the tabs. value is any CSS gradient, and the picker writes one back.

<ColorPicker value={value} onChange={setValue} modes={["linear"]} />
// value: "linear-gradient(90deg, #22C55E 0%, #3E5CEB 100%)"

<ColorPicker value={value} onChange={setValue} modes={["radial"]} />
// value: "radial-gradient(circle at 30% 30%, #FDE68A 0%, #F97316 45%, #BE123C 100%)"

<ColorPicker value={value} onChange={setValue} modes={["conic"]} />
// value: "conic-gradient(from 0deg at 50% 50%, #EF4444, #F59E0B, #22C55E, #3B82F6, #A855F7, #EF4444)"

Repeating gradients (repeating-linear-gradient(...) and the rest) work the same way; toggle Repeating in the ... menu.

Gradients only

For backgrounds that must be a gradient. defaultGradient is what a solid value turns into.

<ColorPicker
  value={value}
  onChange={setValue}
  modes={["linear", "radial", "conic"]}
  defaultGradient="linear-gradient(90deg, #3E5CEB 0%, #22C55E 100%)"
  gradientPresets
/>

Solid colors, no transparency

<ColorPicker value={value} onChange={setValue} modes={["solid"]} alpha={false} formats={["hex", "rgb", "hsl"]} />

Text color with a contrast check

Shows the WCAG ratio and draws the AA line on the color area.

<ColorPicker value={value} onChange={setValue} modes={["solid"]} alpha={false} contrastWith="#FFFFFF" />

OKLCH and wide gamut

<ColorPicker
  value={value} // "oklch(0.62 0.2 265)"
  onChange={setValue}
  modes={["solid"]}
  space="oklch"
  formats={["oklch", "hex", "rgb"]}
  outputFormat="oklch"
/>

Undo and before / after

<ColorPicker value={value} onChange={setValue} history compare />

Saving changes

onChange fires on every frame of a drag. Update the preview there, and save in onChangeComplete, which fires once.

<ColorPicker
  value={layer.fill}
  onChange={(fill) => updateLayerPreview(layer.id, { fill })}
  onChangeComplete={(fill) => saveLayer(layer.id, { fill })}
/>

In a form

ColorField takes a value and an onChange like an input, so it works with any form library:

import { Controller, useForm } from "react-hook-form";
import { ColorField } from "@orshot/colorshot/react";

const { control, handleSubmit } = useForm({ defaultValues: { accent: "#3E5CEB" } });

<Controller
  name="accent"
  control={control}
  render={({ field }) => (
    <ColorField label="Accent" value={field.value} onChange={field.onChange} modes={["solid"]} alpha={false} />
  )}
/>;

Match a stored format

Keep whatever format your app already stores. Here: uppercase hex when opaque, comma rgba() otherwise.

import { formatColor } from "@orshot/colorshot";

const outputFormat = (color) =>
  color.alpha >= 1
    ? formatColor({ ...color, alpha: 1 }, "hex", { upper: true })
    : formatColor(color, "rgb", { legacy: true, fn: "rgba" });

<ColorPicker value={value} onChange={setValue} outputFormat={outputFormat} />;

shadcn/ui theme

/* globals.css. On shadcn/ui v3 (HSL channel tokens) wrap them: hsl(var(--primary)) */
[data-colorshot],
[data-colorshot-field] {
  --cs-accent: var(--primary);
  --cs-bg: var(--popover);
  --cs-fg: var(--popover-foreground);
  --cs-border: var(--border);
  --cs-radius: var(--radius);
}

Using with AI

Install the Colorshot skill to teach your coding agent (Claude Code, Codex, Cursor, GitHub Copilot and others) how to add and configure the picker:

npx skills add rishimohan/colorshot

The API reference is also available for LLMs in llms.txt, and the docs page has a setup prompt you can copy into any agent.

One package

Apps only bundle what they import: a React app never pulls in the Vue code, and React and Vue are optional peer dependencies.

Optional features

All off unless you turn them on.

Always on, no props needed:

• Cmd/Ctrl+C copies the value and Cmd/Ctrl+V applies a pasted color or gradient while the picker has focus
• Two-finger trackpad swipes move the area, sliders, stops and angle dial (the page still scrolls when the swipe started elsewhere)
• Alt-drag a stop to duplicate it, drag a stop off the bar or press Delete to remove it, drag a solid swatch onto the bar to add it
• Switching between solid and gradient keeps the color you are editing on the active stop
• Touch screens get larger thumbs and targets

ColorField

A trigger that opens the picker in a popover. Flips and shifts to stay on screen, closes on Escape, outside click or tab-away, and returns focus to the trigger. Takes every ColorPicker prop.

import { ColorField } from "@orshot/colorshot/react";

<ColorField label="Fill" value={fill} onChange={setFill} gradientPresets history />;

On-canvas gradient handles

Framework-free helpers for drawing gradient handles on your own canvas:

import { gradientHandles, moveGradientHandle } from "@orshot/colorshot";

const result = gradientHandles(value, width, height); // null when value is not a gradient
if (result) {
  const { handles, line } = result; // start / end / stops / center / angle
  const next = moveGradientHandle(value, handles[0].id, x, y, width, height, { snap: shiftKey });
}

API reference

ColorPicker props

ColorPicker (React) and <ColorPicker> (Vue, with v-model and @change-complete) take the same props.

Swatch groups

interface Swatch {
  value: string;
  label?: string; // shown as a tooltip
  id?: string; // your id, passed back to onRemove
}

interface SwatchGroupConfig {
  id: string;
  label?: ReactNode; // the group's tab name
  colors?: (string | Swatch)[] | "default"; // "default" is the built-in palette
  recent?: boolean; // recently used colors, stored under storageKey
  limit?: number; // show at most this many, with a "Show all" toggle
  showIn?: "solid" | "gradient"; // only show the group in one kind of mode
  onAdd?: (value: string) => void; // shows a + button that saves the current value
  onRemove?: (swatch: Swatch) => void; // remove button on hover, Delete on a focused swatch
  onReorder?: (swatches: Swatch[]) => void; // drag (or Alt + arrows) to reorder
  onRename?: (swatch: Swatch, label: string) => void; // double-click or F2
  renderSwatch?: (swatch: Swatch, state: { selected: boolean }) => ReactNode;
  emptyText?: ReactNode; // shown when the group is empty
}

ColorField props

Every ColorPicker prop, plus:

A ref gives you { open(), close(), trigger }.

Parts

For your own layout, compose parts under Picker.Root (it takes the value props above):

import { Picker } from "@orshot/colorshot/react";

<Picker.Root value={value} onChange={setValue}>
  <Picker.Area />
  <Picker.Hue />
  <Picker.Alpha />
  <Picker.Inputs />
  <Picker.Swatches groups={groups} />
</Picker.Root>;

Theming

Set CSS variables on any parent or on the picker. Styles live in @layer colorshot, so your own unlayered CSS (Tailwind utilities included) wins without !important.

.inspector [data-colorshot] {
  --cs-accent: #3e5ceb;
  --cs-width: 100%;
  --cs-area-height: 160px;
}

The documented --cs-* variables, data-part names and the data-state, data-mode, data-theme, data-size and data-variant attributes follow semver.

Localization

Every visible and screen reader string is a label. {placeholders} are filled in for you.

<ColorPicker
  value={value}
  onChange={setValue}
  labels={{
    picker: "Farbwähler",
    solid: "Einfarbig",
    linear: "Linear",
    radial: "Radial",
    conic: "Konisch",
    hue: "Farbton",
    alpha: "Deckkraft",
    stopName: "Farbstopp {index} von {count}",
  }}
/>

Keyboard and gestures

Core helpers

@orshot/colorshot has no framework code and is safe in server code.

import { parseColor, formatColor, contrastRatio, isSafeCssValue } from "@orshot/colorshot";

formatColor(parseColor("#3366ff")!.color, "oklch"); // "oklch(0.5726 0.2338 265.28)"
contrastRatio("#64748b", "#ffffff"); // 4.76
isSafeCssValue(storedValue); // validate stored values before writing them into HTML or CSS

TypeScript

Types ship with the package, for every entry.

import type { ColorPickerProps, ColorFieldProps, SwatchGroupConfig, Swatch, DisplayFormat } from "@orshot/colorshot/react";
import type { OutputFormat, PickerMode, Color } from "@orshot/colorshot";

Next.js and SSR

The React entry is marked "use client": render the components from client components, and import helpers from @orshot/colorshot in server code. The picker renders the same markup on the server and the client. Pass theme from your theme provider after hydration, or leave it unset to follow the OS.

Accessibility

• Checked with axe against WCAG 2.2 AA in the browser test suite
• Every slider, stop and field is keyboard reachable, and sliders announce their value in words through aria-valuetext
• Screen reader labels for every control, all overridable through labels
• High contrast (forced-colors), right-to-left layouts and prefers-reduced-motion are supported
• Touch screens get larger thumbs and targets

Browser support

Current Chrome, Edge, Firefox and Safari. The browser tests run in Chromium, Firefox and WebKit. The eyedropper uses the native EyeDropper API where it exists (Chromium) and hides itself elsewhere, unless you pass eyeDropper={fn}.

Development

pnpm install
pnpm --filter @colorshot/playground dev       # playground on http://localhost:5190
pnpm --filter @colorshot/core test            # parser, conversion and gradient corpus tests
pnpm --filter @colorshot/playground test:e2e  # browser tests on Chromium, Firefox and WebKit
pnpm build && pnpm size                       # build everything and check gzip budgets

See CONTRIBUTING.md for the layout and the rules, and RELEASING.md for publishing.

License

MIT. Free for personal and commercial use: keep the copyright line and license text, which link to https://orshot.com/open-source/colorshot. The color conversion matrices come from CSS Color Module Level 4, see THIRD-PARTY-NOTICES.md.

---

Brought to you by Orshot, the API for automated image, PDF and video generation from templates. MIT License.