<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
<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>
<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>
<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>
<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>
<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>
<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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
alpha | alpha | boolean | false app default | Let the colour carry transparency: an alpha slider and an A channel join the panel. Without it typed alpha is dropped |
clearable | clearable | boolean | false | Make the value clearable |
disabled | disabled | boolean | false | Disable the field |
errorMessage | error-message | string | '' | Error message shown in place of the hint while the field is invalid |
format | format | CColorPickerFormat | '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)` |
hideMessage | hide-message | boolean | false app default | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the field |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
label | label | string | '' | Element label |
labelOnTop | label-on-top | boolean | false app default | Label on top of the field |
name | name | string | '' | The name the colour submits under in a native `<form>`, in the picker's notation |
placeholder | placeholder | string | '' | Placeholder of the input; an example of the notation when empty |
required | required | boolean | false | Set the field as required |
shadow | shadow | boolean | false app default | Shadow variant |
size | size | CFieldSize | 'default' app default | Field height: the 52px default (the shared control height) or the 36px `small` box |
swatches | — | | () => [] | 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 |
swatchesOnly | swatches-only | boolean | false | Limit the choice to the swatches: the field becomes readonly and opens a panel of the swatches alone |
texts | — | | {} app default | UI text overrides (i18n), merged over the English defaults. Objects have no attribute form — bind as a DOM property |
value | value | | null | The colour in the `format` notation, or `null` when empty. Any CSS colour is accepted and shown in the notation |
hideDetails deprecated | hide-details | boolean | false 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
| Event | Detail | Description |
|---|---|---|
change | CColorPickerValue | Fired 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:text | string | Fired 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. |
input | void | Native 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:value | CColorPickerValue | Fired with every value change, each move of a drag included — the `v-model` contract. |
Methods
| Method | Signature | Description |
|---|---|---|
badInput | : boolean (read-only) | Whether the committed text names no colour — the value is then `null` (CONTEXT.md "Bad input"). |
focus | (options?: FocusOptions): void | Focus 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.
| Part | Description |
|---|---|
input | The text input; under `swatches-only` the readonly field |
value-color | The value's colour, painted in the colour button or before the swatch-only field's text; pairs with `original-color` and `new-color` |
panel | The top-layer popover container anchored below the field |
card | The dialog surface inside the panel |
heading-row | The top row of the fullscreen panel (narrow viewports): the field label as heading and the close button |
heading | The field label naming the fullscreen panel |
close | The close button of the fullscreen panel |
area | The saturation × brightness square at the current hue |
area-thumb | The marker of the colour in the area |
hue-slider | The hue slider |
alpha-slider | The alpha slider (`alpha`) |
comparison | The strip of the original colour beside the new one, when the panel opened on a colour |
original-color | The colour the panel opened on; a click restores it |
new-color | The colour the panel holds now |
notation-switch | The HEX | RGB | OKLCH row choosing the channel editor |
notation | One button of the notation switch |
channels | The channel editor: the inputs of one notation |
channel | One channel input |
swatches | The list of swatches |
swatch | One swatch |
actions | The row under the panel body in the fullscreen panel (narrow viewports) |
done | The Done button of the fullscreen panel (narrow viewports): commits what the panel holds and closes |
message | The 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.
| State | Description |
|---|---|
bad-input | Present 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';