Chroma Panel

Search documentation

Find a page or section

ColorInput drops into a form like an input.

Give it a name and it submits with the form, responds to form.reset(), and participates in native validation.

Loading…
color-input-form-demo.tsx
"use client";
 
import { ColorInput } from "chroma-panel";
import { useState } from "react";
 
export default function ColorInputFormDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);
 
  return (
    <form
      className="flex items-center gap-3"
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        setSubmitted(String(data.get("brand")));
      }}
    >
      <ColorInput name="brand" defaultValue="#cc3366" injectStyles={false} />
 
      <button
        type="submit"
        className="rounded-md border border-edge px-3 py-1.5 text-sm font-medium"
      >
        Submit
      </button>
 
      <button
        type="reset"
        className="rounded-md px-3 py-1.5 text-sm font-medium text-muted-foreground"
        onClick={() => setSubmitted(null)}
      >
        Reset
      </button>
 
      {submitted && (
        <span className="font-mono text-sm text-muted-foreground">
          {submitted}
        </span>
      )}
    </form>
  );
}
<form onSubmit={handleSubmit}>
  <ColorInput name="brand" defaultValue="#cc3366" required />
  <button type="submit">Save</button>
</form>

The submitted value is the string in whichever format you set, so a form that needs rgba() gets it without a conversion step on your side.

Validation

required marks the control invalid while it is empty. validationBehavior chooses between the browser's own bubble and an ARIA-only message:

<ColorInput name="brand" required validationBehavior="aria" />

Resetting

form.reset() returns the control to defaultValue, like any native input. A controlled ColorInput is yours to reset — the form cannot change state you own.

API reference

Props

PropTypeDefaultDescription
openbooleanWhether the popover is open, when you control it.
defaultOpenbooleanfalseWhether the popover starts open.
onOpenChange(open: boolean) => voidFires when the popover opens or closes, however it was triggered.
namestringSubmits with the surrounding form under this name. The submitted value is the string in whichever format you set.
formstringAssociates the control with a form by id, for when it cannot be nested inside one.
requiredbooleanfalseMarks the control invalid while it has no value.
readOnlybooleanfalseShows the colour but does not allow changing it. Unlike disabled, the value still submits.
autoCompletestringPassed through to the hidden input backing the control.
validationBehavior"native" | "aria"'native''native' uses the browser's own validation bubble. 'aria' reports the message through ARIA only, for when you render your own.
idstringId on the trigger, so your own <label htmlFor> can point at it.
aria-labelstring'Choose a colour'Accessible name for the trigger, used when there is no visible label.
triggerClassNamestringClass on the swatch button only. Equivalent to classNames.trigger.
valuestring | HsvaThe colour, when you keep it in your own state.Inherited from ChromaPanel.
defaultValuestring | Hsva'#3366cc'The starting colour, when you want the panel to keep it.Inherited from ChromaPanel.
onChange(color: ColorChangeResult) => voidFires continuously while a drag is in progress.Inherited from ChromaPanel.
onChangeComplete(color: ColorChangeResult) => voidFires once when the drag ends. Use it for saving, undo entries and network calls.Inherited from ChromaPanel.
modes(ModeId | string | PickerMode)[]all fiveWhich tabs appear, in the order you list them.Inherited from ChromaPanel.
modestringThe open tab, when you control it.Inherited from ChromaPanel.
defaultModestringfirst modeThe tab to open on.Inherited from ChromaPanel.
onModeChange(mode: string) => voidFires when the reader switches tabs.Inherited from ChromaPanel.
formatColorFormat'hex'Sets the css string on the change result, and the value a form submits.Inherited from ChromaPanel.
showAlphabooleantrueTurn off when opacity is not allowed.Inherited from ChromaPanel.
showEyedropperbooleantrueTurn off to hide the eyedropper even where it is supported.Inherited from ChromaPanel.
showRecentColorsbooleantrueTurn off in a one-shot picker.Inherited from ChromaPanel.
recentColorsstring[]The recent-colour history, when you keep it. Persist it yourself to carry the list between sessions.Inherited from ChromaPanel.
defaultRecentColorsstring[][]The starting history, when you want the panel to keep it.Inherited from ChromaPanel.
onRecentColorsChange(colors: string[]) => voidFires with the whole list whenever a colour is added to it.Inherited from ChromaPanel.
palettesColorPalette[]built-in setReplaces the palette swatches with your own.Inherited from ChromaPanel.
pencilsstring[]built-in 120-colour gridReplaces the pencil grid.Inherited from ChromaPanel.
modePropsRecord<string, Record<string, unknown>>Props spread onto one mode's panel, keyed by mode id. Lets a custom mode take props without the panel knowing about it.Inherited from ChromaPanel.
imageOptionsExtractOptionsShorthand for modeProps.image.extractOptions.Inherited from ChromaPanel.
disabledbooleanfalseMakes the panel read-only.Inherited from ChromaPanel.
theme"dark" | "light"systemForces one theme instead of following the OS.Inherited from ChromaPanel.
showTitleBarbooleantrueTurn off for an inline panel with no chrome.Inherited from ChromaPanel.
titlestring'Colours'The title bar text.Inherited from ChromaPanel.
onClose() => voidFires when the red window control is used. An inline panel has nothing to close, so that control is dimmed until you pass this.Inherited from ChromaPanel.
collapsedbooleanWhether the panel is collapsed to its title bar, when you control it.Inherited from ChromaPanel.
defaultCollapsedbooleanfalseWhether it starts collapsed. Collapsing hides the body with CSS rather than unmounting, so nothing is lost.Inherited from ChromaPanel.
onCollapsedChange(collapsed: boolean) => voidFires when the yellow window control is used.Inherited from ChromaPanel.
sizePanelSizeThe panel size, when you control it.Inherited from ChromaPanel.
defaultSizePanelSize'default'The starting size. 'expanded' widens the panel, and the wheel with it.Inherited from ChromaPanel.
onSizeChange(size: PanelSize) => voidFires when the green window control is used.Inherited from ChromaPanel.
injectStylesbooleantrueTurn off when you import chroma-panel/style.css yourself, as this site does.Inherited from ChromaPanel.
classNamestringClass applied to the panel root.Inherited from ChromaPanel.
classNamesChromaClassNamesClasses applied per part.Inherited from ChromaPanel.
styleReact.CSSPropertiesInline styles on the panel root. Setting the --cp-* custom properties here themes a single panel.Inherited from ChromaPanel.
storeColorStoreAn external colour store, for driving several panels from one colour.Inherited from ChromaPanel.