ColorPicker

Code

import { ColorPicker, Field, FieldLabel } from "@fadymondy/nasaq/web";import { useState } from "react";export function LabelColor() {  const [color, setColor] = useState<string | null>("--nq-tag-teal");  return (    <Field>      <FieldLabel>Label colour</FieldLabel>      <ColorPicker value={color} onValueChange={setColor} aria-label="Label colour" />    </Field>  );}

Pickers · beta

Live examples and controls: ColorPicker in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/color-picker.json

A form control for choosing one colour. The trigger looks like an input and shows the current swatch and its name. It opens a popover with a grid of swatches (the --nq-tag-* palette by default), a hex field that validates what the user types, and an optional "Custom" button that opens the browser's native colour input.

When to useCopy Anchor Link

• Colouring a label, a tag, a calendar or a chart series.
• Letting users choose a brand colour, with a few approved swatches plus a free hex value.

When not to useCopy Anchor Link

• Picking one of a few named options with no colour meaning: use a RadioGroup or a Select.
• Editing tags themselves: use a TagInput.

ImportCopy Anchor Link

import { ColorPicker } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { ColorPicker, Field, FieldLabel } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function LabelColor() {
  const [color, setColor] = useState<string | null>("--nq-tag-teal");
  return (
    <Field>
      <FieldLabel>Label colour</FieldLabel>
      <ColorPicker value={color} onValueChange={setColor} aria-label="Label colour" />
    </Field>
  );
}

Value formatCopy Anchor Link

The value is a plain string, and it is one of two things:

null means no colour. Turn a value into a CSS colour with colorToCss(value): a hex string stays as is, and --nq-tag-red becomes var(--nq-tag-red).

import { colorToCss } from "@fadymondy/nasaq/web";

export const Dot = ({ color }: { color: string }) => <span className="size-3 rounded-full" style={{ backgroundColor: colorToCss(color) }} />;

AnatomyCopy Anchor Link

ColorPicker
├─ trigger                 button rendered through Field.Control      data-slot="color-picker-trigger"
│  └─ chip + name          data-slot="color-picker-chip"
└─ popover                 aria-label "Choose colour"
   ├─ swatch grid          radiogroup                                 data-slot="color-picker-swatches"
   │  └─ swatch            role="radio"                               data-slot="color-picker-swatch"
   ├─ hex field            dir="ltr" text input                       data-slot="color-picker-hex"
   │  └─ error             role="alert"                               data-slot="color-picker-error"
   └─ Custom button        opens <input type="color">                 data-slot="color-picker-custom"

APICopy Anchor Link

ColorPickerCopy Anchor Link

Types and helpersCopy Anchor Link

ExamplesCopy Anchor Link

Your own swatchesCopy Anchor Link

import { ColorPicker } from "@fadymondy/nasaq/web";

export function BrandColor() {
  return (
    <ColorPicker
      aria-label="Brand colour"
      columns={3}
      allowNative={false}
      swatches={[
        { value: "--nq-tag-blue", label: "Brand blue" },
        { value: "--nq-tag-green", label: "Success green" },
        { value: "--nq-tag-red", label: "Alert red" },
      ]}
    />
  );
}

In a formCopy Anchor Link

import { ColorPicker, Field, FieldError, FieldLabel } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Required() {
  const [color, setColor] = useState<string | null>(null);
  return (
    <Field invalid={!color}>
      <FieldLabel>Colour</FieldLabel>
      <ColorPicker name="color" value={color} onValueChange={setColor} invalid={!color} aria-label="Colour" />
      <FieldError match>Choose a colour.</FieldError>
    </Field>
  );
}

ArabicCopy Anchor Link

import { ColorPicker, Field, FieldLabel, NasaqProvider } from "@fadymondy/nasaq/web";

export function LabelColorAr() {
  return (
    <NasaqProvider locale="ar" target="scope">
      <Field>
        <FieldLabel>لون الوسم</FieldLabel>
        <ColorPicker defaultValue="--nq-tag-red" aria-label="لون الوسم" />
      </Field>
    </NasaqProvider>
  );
}

AccessibilityCopy Anchor Link

The trigger is a button with aria-label "Choose colour: Teal". The popover is labelled "Choose colour". The swatch grid is a radiogroup (Base UI RadioGroup), each swatch is a role="radio" with an accessible name from its label, and the selected swatch also gets a ring, so the state is not colour only.

• The hex field has an accessible name; an invalid entry sets aria-invalid and shows an announced error.
• Caller must localise: aria-label, placeholder, and the label of every custom swatch. The built-in strings and the tag palette names come in English and Arabic.

RTL & i18nCopy Anchor Link

• The grid, trigger and buttons use logical layout, so they mirror with dir.
• The hex field is always dir="ltr"; hex digits never reverse in Arabic.
• Palette names and every built-in string switch to Arabic when the locale is ar.

Styling & tokensCopy Anchor Link

• Default swatches are --nq-tag-* variables. There are no hex colours in the component; hex only ever comes from the user's data.
• Surfaces use bg-card, border-input, border-nq-line-strong, the popover uses bg-popover; the focus ring is nq-focus; errors use nq-danger.
• Slots: color-picker-trigger, color-picker-chip, color-picker-swatches, color-picker-swatch (data-checked), color-picker-hex, color-picker-error, color-picker-custom.
• Extend the trigger with className; never override colours with raw hex.

Do / Don'tCopy Anchor Link

• Do store a --nq-tag-* name when the colour is a design choice, so it adapts to dark mode and brands.
• Do give custom swatches a label; without it a screen reader has nothing to say.
• Don't assume the value is hex: pass it through colorToCss before using it in a style.
• Don't save the resolved colour of a token as hex unless you want it frozen.

RelatedCopy Anchor Link

• Popover · RadioGroup · Field · TagInput

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-pickers-color-picker--docs