docs / core / color-field

ColorField

a color input: a swatch and a hex field that validates as you type, bound to one solid value.

intensity · recedesrsc · client

provenance

authored in usva

layer

core / primitives

intensity

recedes · safe anywhere, including dense surfaces

composition

theme editors and settings panels that repaint a role tokenwire onValueChange to a css variable, never to a component propnever to paint one button. paint the token, or add the missing rolenot a full picker. six digits and a swatch is the whole surface

a11y

the swatch is named by swatchLabel · the hex input is labelled and sets aria-invalid on a malformed draft · both carry the focus ringjest-axe
live demo · try it out
customize
labelnames the field
valuea hex colour; a bad one paints invalid
disableddims the field and its swatch
usagecopy
import { ColorField } from "@usva-ui/react/primitives/color-field";

<ColorField label="Accent" defaultValue="#a78bfa" />

props

proptypedefaultnotes
valuestring—controlled hex, #rrggbb.
defaultValuestring"#000000"initial hex when uncontrolled.
onValueChange(hex: string) => void—fires only when the text parses as six-digit hex. a malformed draft never escapes the field.
labelReactNode—label for the hex input.
swatchLabelstring"Pick a color"accessible name for the swatch, which is its own focusable control.
disabledbooleanfalsedisables both the swatch and the hex input.
idstring—id for the hex input. generated if omitted.

get it

bun add @usva-ui/reactcopy
usagecopy
import { ColorField } from "@usva-ui/react/primitives/color-field";

<ColorField
  label="Accent"
  value={accent}
  onValueChange={(hex) => {
    setAccent(hex);
    document.documentElement.style.setProperty("--usva-accent", hex);
  }}
/>