给 ColorInput 设置 name,它就成了表单的一部分:提交时带上一个颜色字符串,支持必填校验,表单重置时回到 defaultValue。
正在加载在线示例,代码在下方。
"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
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | — | Whether the popover is open, when you control it. |
| defaultOpen | boolean | false | Whether the popover starts open. |
| onOpenChange | (open: boolean) => void | — | Fires when the popover opens or closes, however it was triggered. |
| name | string | — | Submits with the surrounding form under this name. The submitted value is the string in whichever format you set. |
| form | string | — | Associates the control with a form by id, for when it cannot be nested inside one. |
| required | boolean | false | Marks the control invalid while it has no value. |
| readOnly | boolean | false | Shows the color but does not allow changing it. Unlike disabled, the value still submits. |
| autoComplete | string | — | Passed 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. |
| id | string | — | Id on the trigger, so your own <label htmlFor> can point at it. |
| aria-label | string | 'Choose a color' | Accessible name for the trigger, used when there is no visible label. |
| triggerClassName | string | — | Class on the swatch button only. Equivalent to classNames.trigger. |
| value | string | Hsva | — | The color, when you keep it in your own state.Inherited from ChromaPanel. |
| defaultValue | string | Hsva | '#3366cc' | The starting color, when you want the panel to keep it.Inherited from ChromaPanel. |
| onChange | (color: ColorChangeResult) => void | — | Fires continuously while a drag is in progress.Inherited from ChromaPanel. |
| onChangeComplete | (color: ColorChangeResult) => void | — | Fires once when the drag ends. Use it for saving, undo entries and network calls.Inherited from ChromaPanel. |
| onValueChange | (color: ColorChangeResult, meta: ColorChangeMeta) => void | — | Fires continuously with interaction metadata, including the change source.Inherited from ChromaPanel. |
| onValueCommit | (color: ColorChangeResult, meta: ColorChangeMeta) => void | — | Fires once per completed interaction with phase and source metadata.Inherited from ChromaPanel. |
| modes | readonly (ModeId | string | PickerMode)[] | all five | Which tabs appear, in the order you list them.Inherited from ChromaPanel. |
| mode | string | — | The open tab, when you control it.Inherited from ChromaPanel. |
| defaultMode | string | first mode | The tab to open on.Inherited from ChromaPanel. |
| onModeChange | (mode: string) => void | — | Fires when the reader switches tabs.Inherited from ChromaPanel. |
| format | ColorFormat | 'hex' | Sets the css string on the change result, and the value a form submits.Inherited from ChromaPanel. |
| showAlpha | boolean | true | Turn off when opacity is not allowed.Inherited from ChromaPanel. |
| showEyedropper | boolean | true | Turn off to hide the eyedropper even where it is supported.Inherited from ChromaPanel. |
| showCopyButton | boolean | true | Show a button that copies the color in the configured format.Inherited from ChromaPanel. |
| showRecentColors | boolean | true | Turn off in a one-shot picker.Inherited from ChromaPanel. |
| recentColors | string[] | — | The recent-color history, when you keep it. Persist it yourself to carry the list between sessions.Inherited from ChromaPanel. |
| defaultRecentColors | string[] | [] | The starting history, when you want the panel to keep it.Inherited from ChromaPanel. |
| onRecentColorsChange | (colors: string[]) => void | — | Fires with the whole list whenever a color is added to it.Inherited from ChromaPanel. |
| palettes | ColorPalette[] | built-in set | Replaces the palette swatches with your own.Inherited from ChromaPanel. |
| pencils | string[] | built-in 120-color grid | Replaces the pencil grid.Inherited from ChromaPanel. |
| modeProps | Record<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. |
| imageOptions | ExtractOptions | — | Shorthand for modeProps.image.extractOptions.Inherited from ChromaPanel. |
| disabled | boolean | false | Makes the panel read-only.Inherited from ChromaPanel. |
| theme | "dark" | "light" | system | Forces one theme instead of following the OS.Inherited from ChromaPanel. |
| showTitleBar | boolean | true | Turn off for an inline panel with no chrome.Inherited from ChromaPanel. |
| title | string | 'Colors' | The title bar text.Inherited from ChromaPanel. |
| onClose | () => void | — | Fires 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. |
| collapsed | boolean | — | Whether the panel is collapsed to its title bar, when you control it.Inherited from ChromaPanel. |
| defaultCollapsed | boolean | false | Whether it starts collapsed. Collapsing hides the body with CSS rather than unmounting, so nothing is lost.Inherited from ChromaPanel. |
| onCollapsedChange | (collapsed: boolean) => void | — | Fires when the yellow window control is used.Inherited from ChromaPanel. |
| size | PanelSize | — | The panel size, when you control it.Inherited from ChromaPanel. |
| defaultSize | PanelSize | 'default' | The starting size. 'expanded' widens the panel, and the wheel with it.Inherited from ChromaPanel. |
| onSizeChange | (size: PanelSize) => void | — | Fires when the green window control is used.Inherited from ChromaPanel. |
| injectStyles | boolean | true | Turn off when you import chroma-panel/style.css yourself, as this site does.Inherited from ChromaPanel. |
| className | string | — | Class applied to the panel root.Inherited from ChromaPanel. |
| classNames | ChromaClassNames | — | Classes applied per part.Inherited from ChromaPanel. |
| style | React.CSSProperties | — | Inline styles on the panel root. Setting the --cp-* custom properties here themes a single panel.Inherited from ChromaPanel. |
| store | ColorStore | — | An external color store, for driving several panels from one color.Inherited from ChromaPanel. |