ColorField
color-fieldEdits a hexadecimal color through a swatch, system picker, text input, and shorthand expansion.
Usage
Controlled
value + onValueChange controlled. The callback parameter is always the normalized #rrggbb - input #abc will throw #aabbcc.
const [hex, setHex] = useState("#38e8ff");
<ColorField value={hex} onValueChange={setHex} className="w-40" aria-label="Main Color" />Three sizes
sm / md / lg, the color block is scaled accordingly, and it is the same shell variant as Input.
<ColorField size="sm" defaultValue="#38e8ff" className="w-32" />
<ColorField size="md" defaultValue="#7c5cff" className="w-36" />
<ColorField size="lg" defaultValue="#34e8a4" className="w-40" />Colorless block/disabled/marked red
showSwatch=false Only text is left; when an unparsable value is entered, the component itself will be marked red, and there is no need to pass invalid externally.
<ColorField showSwatch={false} defaultValue="#38e8ff" className="w-32" />
<ColorField disabled defaultValue="#6b7d93" className="w-36" />
<ColorField invalid defaultValue="#ff6b6b" className="w-36" />When to use
Use ColorField for a compact single-line color value in a form, such as a theme settings table, design-token editor, or chart-color row where the value is known and adjusted occasionally.
For a full saturation panel with HEX/RGB/HSL switching, use ColorPicker. For a small fixed palette, use ColorSwatchPicker. ColorField is designed to fit beside a label or description without expanding the form row.
Import
import { ColorField, normalizeHex, isHexColor } from "@hulianui/ui"Props
Inherit native <input> properties (size/prefix/value/defaultValue/onChange/type have been overridden).
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | — | controlled value. Accept #rgb / #rrggbb / None # writing method, the internal unified standard is lowercase #rrggbb |
| defaultValue | string | "#3b82f6" | uncontrolled initial value |
| showSwatch | boolean | true | Click on the color block on the left to open the system color picker |
| size | "sm" | "md" | "lg" | "md" | Size (same shell variant as Input, color blocks scale accordingly) |
| invalid | boolean | false | Marked red when used independently; automatically driven by Field.Root invalid in hulian Field |
| disabled | boolean | false | Disable both text box and color picker |
Events
| Event | Type | Description |
|---|---|---|
| onValueChange | (hex: string) => void | Called with a normalized `#rrggbb` value after valid input; invalid drafts do not trigger it. |
Utility functions
| function | sign | illustrate |
|---|---|---|
| normalizeHex | (input: string) => string | null | Normalized to lowercase #rrggbb; cannot be parsed and returns null (no error thrown, no default color) |
| isHexColor | (input: string) => boolean | Whether it can be parsed (3/6 bits, # can be omitted) |
Two pure functions are exported separately: "Which writing methods are considered legal colors?" The consumer must also use it (for example, verify before importing a theme configuration), and should not only live inside the component.
Usage guidelines
- A short hex value is shorthand, not a different number.
#abcexpands to#aabbccby repeating each digit, not to#abc000.normalizeHexfollows this rule. - Do not bind the normalized controlled value directly to the text input. Doing so would reject the first partial character, for example changing
#3back to the previous value before the user can finish. ColorField keeps an internal draft while typing, emits only after parsing succeeds, and normalizes the draft on blur. Preserve this behavior in extensions. onValueChangedoes not fire for an invalid draft, so consumers receive only usable colors. Listen to nativeonInputif the application must observe incomplete input.- An unparseable external
valuefalls back to the internal value instead of crashing. This is defensive behavior, not a contract; controlled consumers should still provide valid colors. - The swatch overlays a transparent native
input[type=color]on a token-colored span because native color-input appearance is not fully styleable. Avoid overridingappearance, which can break the control.
Related
ColorPicker · ColorSwatchPicker · Input · Field · SecretField