CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-color-picker>

A colour field that takes any typed CSS colour, or opens a panel for picking one: a colour area, hue and alpha sliders, per-channel inputs and swatches — or swatches alone under `swatches-only`.

Usage

Value

The value is a CSS colour string in the field's notation — '#1f6feb' by default — or null when the field is empty. Bind it with v-model, or listen for change:

<c-color-picker v-model="color" label="Colour" />

Notation

format sets the notation the value is written in, and every emission with it: hex (the default) gives #1f6feb, rgb gives rgb(31 111 235) and oklch gives oklch(0.5686 0.202 259.7). Whichever notation a colour arrives in — typed, picked or set from outside — the field shows it, and the value carries it, in this one. The notation is an app default, so an app can set it once with applyDefaults({ 'c-color-picker': { format: 'oklch' } }).

Every colour the picker holds is an 8-bit sRGB colour — what #rrggbb can write — and each notation spells it at the fewest decimals that read back to the same colour. Switching format therefore never moves the colour, and an oklch() typed with four decimals can come back with fewer.

The HEX | RGB | OKLCH switch inside the panel only chooses which channel inputs show. It never changes the value or its notation.

Typing

The field is typeable first: clicking into it or focusing it never opens the panel. Text is read when the user presses Enter or leaves the input, never per keystroke, and any CSS colour reads: #fff, 1f6feb without its #, red, hsl(210 80% 50%), rgba(31, 111, 235, 0.5), color(display-p3 1 0 0). The field then shows the colour in its notation.

A colour outside sRGB — oklch(0.7 0.3 150), rgb(300 0 0) — is brought into it as it is read, keeping its lightness and hue and lowering its chroma, the way a browser paints it on an ordinary screen. It is not an error.

Text that names no colour — blurple, var(--brand) — is bad input: the text stays as the user typed it, the value becomes null, and the host exposes the bad-input custom state and a read-only badInput property. The component never shows an error of its own; deciding whether bad input is an error, and saying so, is the consumer's validation, and only a <form> without novalidate stops a submit on it:

<c-color-picker
  v-model="color"
  :error-message="error"
  :invalid="!!error"
  label="Colour"
  @change:text="error = $event.target.badInput ? 'Enter a colour' : ''"
/>

Every commit of typed text fires change:text with the text as typed.

Alpha

Colours are opaque unless alpha is set. With it the panel gains an alpha slider and an A channel, and the value carries alpha whenever it is below 1: #1f6feb80, rgb(31 111 235 / 0.5). An opaque colour is written the same with or without alpha. Without it, alpha in typed text is dropped.

The panel

The colour button at the field's trailing edge — painted with the current colour — or Alt+ArrowDown in the input opens the panel. It is a dialog: focus moves onto the colour area, and Tab cycles through the area, the sliders, the original colour, the notation switch, the channel inputs and the swatches until the panel closes. Focus returns to the input when it does.

Key In the colour area
ArrowLeft / ArrowRight Less / more saturation
ArrowUp / ArrowDown More / less brightness
Shift + arrow Ten steps
PageUp / PageDown Ten steps of brightness
Home / End No / full saturation
Enter Close
Escape Close; what was picked stays (the original colour restores it)

A channel input commits on Enter or when it is left, clamped to its range; text that is no number reverts. ArrowUp and ArrowDown nudge the channel by one step, Shift by ten, and each nudge commits.

Every pick commits at once and the panel stays open, so a colour can be tuned in several moves (on a narrow viewport picks wait for a Done button instead; see Narrow viewports). An empty field's panel opens on the first swatch, or on white, without committing anything.

Comparing with the original

When the panel opens on a colour, a strip under the sliders shows that original colour on the left beside the colour being picked on the right, so every change can be judged against where it started. Clicking the original — or Enter or Space on it — restores it: in the anchored panel it commits like any pick, and in the fullscreen panel it becomes the colour Done commits. An empty field's panel has no comparison, and neither has a swatch-only panel.

Drag events

A drag on the colour area or a slider updates the value as it moves: every move fires update:value and input, so v-model follows the pointer, and change fires once, when the pointer is released. Save on change to avoid work on every move. A click, a key press, a channel entry and a swatch pick fire all three at once.

Swatches

swatches offers predefined colours under the picker. Each is a CSS colour, or a { value, name } object whose name is what assistive technology reads — otherwise it reads the colour's spelling. Bind the array as a property:

<c-color-picker
  v-model="color"
  :swatches="[
    { value: '#1f6feb', name: 'Ocean' },
    { value: '#e5534b', name: 'Coral' },
  ]"
  label="Tag colour"
/>

The swatches are one Tab stop: the arrow keys move between them without picking, and Enter, Space or a click picks. A swatch that names no colour is skipped with a console warning.

Swatches only

swatches-only limits the choice to the swatches. The field becomes readonly and shows the picked swatch's colour and name; a click, Enter or Alt+ArrowDown opens a panel of the swatches alone, and a pick commits and closes it, as in c-select. Name every swatch in this mode — the name is what the field shows, and a console warning says so when one is missing. A value set from outside that matches no swatch is shown spelled in its notation.

Texts

The panel's labels are English unless texts replaces them. Set them app-wide with applyDefaults({ 'c-color-picker': { texts } }).

Narrow viewports

On a viewport narrower than 760px the panel opens as a fullscreen panel: a heading row with the field's label and a close button above the picker. The panel ends in a Done button, and there picks wait in the panel instead of committing: nothing is emitted until Done commits the colour and closes the panel. The close button and Escape close the panel without a change, and so does the window growing past 760px while it is open. Under swatches-only there is no Done button: a pick commits and closes, as everywhere else.

Related

c-select lists named choices of any kind; reach for it when the options are not colours. The browser's own <input type="color"> has no notation, alpha, swatches or keyboard-operable panel.

Examples

Alpha
Vue React Angular TypeScript
<template>
  <div>
    <c-color-picker
      v-model="color"
      format="rgb"
      hint="Drag the alpha slider for transparency"
      label="Overlay colour"
      alpha
    />

    <p>Value: {{ color ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const color = ref<null | string>('rgb(31 111 235 / 0.5)');
</script>
Basic
Vue React Angular TypeScript
<template>
  <div>
    <c-color-picker
      v-model="color"
      hint="Type any CSS colour or open the picker"
      label="Colour"
      clearable
    />

    <p>Value: {{ color ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const color = ref<null | string>('#1f6feb');
</script>
Notation
Vue React Angular TypeScript
<template>
  <div>
    <c-color-picker
      v-model="color"
      format="oklch"
      hint="The value is always written as oklch()"
      label="Brand colour"
    />

    <p>Value: {{ color ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const color = ref<null | string>('oklch(0.5686 0.202 259.7)');
</script>
Swatches only
Vue React Angular TypeScript
<template>
  <div>
    <c-color-picker
      v-model="color"
      :swatches
      hint="One of the project colours"
      label="Project colour"
      swatches-only
    />

    <p>Value: {{ color ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CColorPickerSwatch } from '@cscfi/csc-ui';

import { ref } from 'vue';

// Name every swatch: the name is what the field shows and what assistive
// technology reads.
const swatches: CColorPickerSwatch[] = [
  { name: 'Ocean', value: '#1f6feb' },
  { name: 'Coral', value: '#e5534b' },
  { name: 'Moss', value: '#57ab5a' },
  { name: 'Sand', value: '#c69026' },
  { name: 'Plum', value: '#986ee2' },
  { name: 'Slate', value: '#768390' },
];

const color = ref<null | string>('#57ab5a');
</script>
Swatches
Vue React Angular TypeScript
<template>
  <div>
    <c-color-picker
      v-model="color"
      :swatches
      hint="Pick a suggestion or any other colour"
      label="Label colour"
    />

    <p>Value: {{ color ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CColorPickerSwatch } from '@cscfi/csc-ui';

import { ref } from 'vue';

const swatches: CColorPickerSwatch[] = [
  { name: 'Ocean', value: '#1f6feb' },
  { name: 'Coral', value: '#e5534b' },
  { name: 'Moss', value: '#57ab5a' },
  { name: 'Sand', value: '#c69026' },
  { name: 'Plum', value: '#986ee2' },
  { name: 'Slate', value: '#768390' },
];

const color = ref<null | string>(null);
</script>
Texts
Vue React Angular TypeScript
<template>
  <div>
    <c-color-picker
      v-model="color"
      :swatches
      :texts
      hint="Kirjoita väri tai valitse se"
      label="Väri"
      alpha
    />

    <p>Value: {{ color ?? 'null' }}</p>
  </div>
</template>

<script setup lang="ts">
import type { CColorPickerSwatch, CColorPickerTexts } from '@cscfi/csc-ui';

import { ref } from 'vue';

// Every text, so none falls back to English.
const texts: CColorPickerTexts = {
  alpha: 'Läpinäkyvyys',
  blue: 'Sininen',
  brightness: 'Kirkkaus',
  chooseColor: 'Valitse väri',
  chroma: 'Kroma',
  clearSelection: 'Tyhjennä',
  closePanel: 'Sulje',
  done: 'Valmis',
  green: 'Vihreä',
  hex: 'Heksa',
  hue: 'Sävy',
  lightness: 'Valoisuus',
  notation: 'Merkintätapa',
  openPicker: 'Avaa värivalitsin',
  red: 'Punainen',
  restoreOriginal: 'Palauta alkuperäinen väri',
  saturation: 'Kylläisyys',
  swatches: 'Värimallit',
  toggleSwatches: 'Näytä värimallit',
};

const swatches: CColorPickerSwatch[] = [
  { name: 'Meri', value: '#1f6feb' },
  { name: 'Koralli', value: '#e5534b' },
  { name: 'Sammal', value: '#57ab5a' },
];

const color = ref<null | string>('#1f6feb');
</script>

API reference

<c-color-picker>

A colour field that takes any typed CSS colour, or opens a panel for picking one: a colour area, hue and alpha sliders, per-channel inputs and swatches — or swatches alone under `swatches-only`.

Properties

PropertyAttributeTypeDefaultDescription
alphaalphabooleanfalse app default Let the colour carry transparency: an alpha slider and an A channel join the panel. Without it typed alpha is dropped
clearableclearablebooleanfalse Make the value clearable
disableddisabledbooleanfalse Disable the field
errorMessageerror-messagestring'' Error message shown in place of the hint while the field is invalid
formatformatCColorPickerFormat'hex' app default The notation the value is written in — and every emission with it: `#rrggbb`, `rgb(r g b)` or `oklch(l c h)`
hideMessagehide-messagebooleanfalse app default Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the field
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
labellabelstring'' Element label
labelOnToplabel-on-topbooleanfalse app default Label on top of the field
namenamestring'' The name the colour submits under in a native `<form>`, in the picker's notation
placeholderplaceholderstring'' Placeholder of the input; an example of the notation when empty
requiredrequiredbooleanfalse Set the field as required
shadowshadowbooleanfalse app default Shadow variant
sizesizeCFieldSize'default' app default Field height: the 52px default (the shared control height) or the 36px `small` box
swatches—CColorPickerSwatch[]() => [] Predefined colours offered under the picker — CSS colours, or `{ value, name }` objects whose name is read out and shown. Arrays have no attribute form — bind as a DOM property
swatchesOnlyswatches-onlybooleanfalse Limit the choice to the swatches: the field becomes readonly and opens a panel of the swatches alone
texts—CColorPickerTexts{} app default UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property
valuevalueCColorPickerValuenull The colour in the `format` notation, or `null` when empty. Any CSS colour is accepted and shown in the notation
hideDetails deprecated hide-detailsbooleanfalse app default Deprecated. Use `hide-message`. Hide the hint and error messages

app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.

Events

EventDetailDescription
changeCColorPickerValueFired when the value changes — a pick in the panel, typed text committed, the field cleared — carrying the colour in the `format` notation, or `null`. A drag on the area or a slider fires it once, on release.
change:textstringFired on every commit of typed text (Enter or leaving the input) with the text as typed. Read `badInput` to tell whether it named a colour.
inputvoidNative bubbling input event dispatched alongside every value change — each move of a drag included — so a plain `v-model` stays in sync. Carries no detail.
update:valueCColorPickerValueFired with every value change, each move of a drag included — the `v-model` contract.

Methods

MethodSignatureDescription
badInput: boolean (read-only)Whether the committed text names no colour — the value is then `null` (CONTEXT.md "Bad input").
focus(options?: FocusOptions): voidFocus its input (the readonly combobox under `swatches-only`), as `focus()` does on a native control: the element renders no box of its own to take it.

CSS parts

Style from outside with c-color-picker::part(name) — parts are the library's only styling customization API.

PartDescription
inputThe text input; under `swatches-only` the readonly field
value-colorThe value's colour, painted in the colour button or before the swatch-only field's text; pairs with `original-color` and `new-color`
panelThe top-layer popover container anchored below the field
cardThe dialog surface inside the panel
heading-rowThe top row of the fullscreen panel (narrow viewports): the field label as heading and the close button
headingThe field label naming the fullscreen panel
closeThe close button of the fullscreen panel
areaThe saturation × brightness square at the current hue
area-thumbThe marker of the colour in the area
hue-sliderThe hue slider
alpha-sliderThe alpha slider (`alpha`)
comparisonThe strip of the original colour beside the new one, when the panel opened on a colour
original-colorThe colour the panel opened on; a click restores it
new-colorThe colour the panel holds now
notation-switchThe HEX | RGB | OKLCH row choosing the channel editor
notationOne button of the notation switch
channelsThe channel editor: the inputs of one notation
channelOne channel input
swatchesThe list of swatches
swatchOne swatch
actionsThe row under the panel body in the fullscreen panel (narrow viewports)
doneThe Done button of the fullscreen panel (narrow viewports): commits what the panel holds and closes
messageThe hint / error message area below the field (always reserved unless `hide-message`)

Custom states

Select on the host's live state with c-color-picker:state(name) — combine with ::part() for per-state styling, e.g. c-color-picker:state(checked)::part(indicator) targets the indicator only while checked.

StateDescription
bad-inputPresent while committed text names no colour

Types

Importable from the package root: import type { … } from '@cscfi/csc-ui'

CColorPickerFormat

The notation a colour picker's value is written in (CONTEXT.md "Notation").

export type CColorPickerFormat = 'hex' | 'oklch' | 'rgb';
CColorPickerSwatch

A predefined colour: a CSS colour, or one with a name for assistive technology and the swatch-only field.

export type CColorPickerSwatch = { name?: string; value: string } | string;
CColorPickerTexts

UI texts of `c-color-picker`, merged key by key over the English defaults.

export interface CColorPickerTexts {
  /** Accessible name of the alpha slider and the A channel. */
  alpha?: string;

  /** Accessible name of the blue channel. */
  blue?: string;

  /** Accessible name of the colour area's vertical axis. */
  brightness?: string;

  /** Accessible name of the dialog when the field has no label. */
  chooseColor?: string;

  /** Accessible name of the chroma channel. */
  chroma?: string;

  /** Accessible label of the clear button. */
  clearSelection?: string;

  /** Accessible label of the close button in the fullscreen panel (narrow viewports). */
  closePanel?: string;

  /** Label of the Done button in the fullscreen panel (narrow viewports). */
  done?: string;

  /** Accessible name of the green channel. */
  green?: string;

  /** Accessible name of the hex channel. */
  hex?: string;

  /** Accessible name of the hue slider and the OKLCH hue channel. */
  hue?: string;

  /** Accessible name of the lightness channel. */
  lightness?: string;

  /** Accessible name of the notation switch. */
  notation?: string;

  /** Accessible label of the colour button. */
  openPicker?: string;

  /** Accessible name of the red channel. */
  red?: string;

  /** Accessible label of the original colour in the colour comparison: a click restores it. */
  restoreOriginal?: string;

  /** Accessible name of the colour area's horizontal axis. */
  saturation?: string;

  /** Accessible name of the swatch list. */
  swatches?: string;

  /** Accessible label of the swatch-only field's chevron button. */
  toggleSwatches?: string;
}
CColorPickerValue

Value of `c-color-picker`: a colour in its `format` notation, or `null` when empty.

export type CColorPickerValue = null | string;
CFieldSize shared

Field height of the form controls built on `c-input`. `default` is the 44px field; `small` is the 36px field. Owned here because the value passes from the wrapping control (`c-select`) into `c-input`.

export type CFieldSize = 'default' | 'small';