Chroma Panel

搜索文档

查找页面或章节

EN

提交、校验、标注和重置颜色值。

ColorInput 设置 name,它就成了表单的一部分:提交时带上一个颜色字符串,支持必填校验,表单重置时回到 defaultValue

正在加载在线示例,代码在下方。

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>

提交的值是按你设置的 format 生成的字符串,所以需要 rgba() 的表单可以直接拿到,不用你再转换一次。所有格式见序列化

要给它加标签,就给它设置 id,再让你自己的 <label htmlFor> 指向它。如果没有可见的标签,就传入 aria-label。更多内容见无障碍功能

校验

设置 required 后,控件为空时会被标记为无效。validationBehavior 决定是使用浏览器自带的气泡提示,还是只通过 ARIA 提供提示信息:

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

重置

和原生输入框一样,form.reset() 会把控件恢复为 defaultValue。受控的 ColorInput 则需要你自己重置,因为表单改不了由你掌管的状态。详见受控与非受控

API 参考

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 color 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 color'Accessible name for the trigger, used when there is no visible label.
triggerClassNamestringClass on the swatch button only. Equivalent to classNames.trigger.
valuestring | HsvaThe color, when you keep it in your own state.Inherited from ChromaPanel.
defaultValuestring | Hsva'#3366cc'The starting color, 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.
onValueChange(color: ColorChangeResult, meta: ColorChangeMeta) => voidFires continuously with interaction metadata, including the change source.Inherited from ChromaPanel.
onValueCommit(color: ColorChangeResult, meta: ColorChangeMeta) => voidFires once per completed interaction with phase and source metadata.Inherited from ChromaPanel.
modesreadonly (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.
showCopyButtonbooleantrueShow a button that copies the color in the configured format.Inherited from ChromaPanel.
showRecentColorsbooleantrueTurn off in a one-shot picker.Inherited from ChromaPanel.
recentColorsstring[]The recent-color 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 color is added to it.Inherited from ChromaPanel.
palettesColorPalette[]built-in setReplaces the palette swatches with your own.Inherited from ChromaPanel.
pencilsstring[]built-in 120-color 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'Colors'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 color store, for driving several panels from one color.Inherited from ChromaPanel.