Colour input

VColorInput is a form field holding a colour. It can be typed in any format, and the swatch at its start opens VColorPicker in a panel.

Usage

vue

Brand colour

Hex, rgb(), hsl() or oklch().

<script setup lang="ts">
import { ref } from 'vue'
import { VColorInput } from 'vectis-ui'

const color = ref<string | null>('#3b82f6')
</script>

<template>
  <div class="column">
    <VColorInput v-model="color" label="Brand colour" hint="Hex, rgb(), hsl() or oklch()." />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

Examples

Formats

The field accepts hex, rgb(), hsl() and oklch(). Enter or leaving the field rewrites the colour in format; anything else puts the field back as it was.

vue

RGB

OKLCH

<script setup lang="ts">
import { ref } from 'vue'
import { VColorInput } from 'vectis-ui'

const rgb = ref<string | null>('rgb(22 163 74)')
const oklch = ref<string | null>('oklch(62.7% 0.17 149.2)')
</script>

<template>
  <div class="column">
    <VColorInput v-model="rgb" format="rgb" label="RGB" />
    <VColorInput v-model="oklch" format="oklch" label="OKLCH" />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

Opacity and swatches

alpha and swatches are passed to the picker. The swatch in the field shows the opacity over a checkerboard.

vue

<script setup lang="ts">
import { ref } from 'vue'
import { VColorInput } from 'vectis-ui'

const color = ref<string | null>('rgb(14 165 233 / 0.6)')
const swatches = ['#0ea5e9', '#16a34a', '#f59e0b', '#e11d48', '#7c3aed', '#0f172a']
</script>

<template>
  <div class="column">
    <VColorInput v-model="color" format="rgb" alpha :swatches="swatches" label="Background" />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

Clearable

clearable adds a cross that sets the value to null.

vue

Highlight

<script setup lang="ts">
import { ref } from 'vue'
import { VColorInput } from 'vectis-ui'

const color = ref<string | null>('#7c3aed')
</script>

<template>
  <div class="column">
    <VColorInput v-model="color" label="Highlight" placeholder="No colour" clearable />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

Validation

VColorInput follows the field model: error replaces the hint and is announced. Attributes such as name and required go to the text field.

vue

Theme colour

Choose a colour for the theme.

<script setup lang="ts">
import { ref } from 'vue'
import { VColorInput } from 'vectis-ui'

const color = ref<string | null>(null)
</script>

<template>
  <div class="column">
    <VColorInput
      v-model="color"
      label="Theme colour"
      hint="Used for buttons and links."
      :error="color ? undefined : 'Choose a colour for the theme.'"
      required
    />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

Sizes

size sets the height of the field to 32, 40 or 48 pixels.

vue

<script setup lang="ts">
import { ref } from 'vue'
import { VColorInput } from 'vectis-ui'

const rows = ref(
  (['sm', 'md', 'lg'] as const).map((size) => ({ size, color: '#16a34a' as string | null })),
)
</script>

<template>
  <div class="column">
    <VColorInput
      v-for="row in rows"
      :key="row.size"
      v-model="row.color"
      :size="row.size"
      :label="row.size"
    />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

Read-only and disabled

readonly shows the colour without a picker. disabled blocks the field and the swatch.

vue

Read-only

Disabled

<script setup lang="ts">
import { VColorInput } from 'vectis-ui'
</script>

<template>
  <div class="column">
    <VColorInput model-value="#7c3aed" label="Read-only" readonly />
    <VColorInput model-value="#7c3aed" label="Disabled" disabled />
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: var(--vectis-space-5);
  max-inline-size: 20rem;
}
</style>

API

Props

Prop	Type	Default
`format`	`ColorFormat'hex' \| 'rgb' \| 'hsl' \| 'oklch'`	`'hex'`
How the value is written. The field accepts all four formats.
`alpha`	`boolean`	`false`
Adds an opacity track to the picker and writes the alpha below 1.
`swatches`	`ColorSwatch[]`	none
Preset colours offered in the picker.
`hideEyeDropper`	`boolean`	`false`
Hides the picker eyedropper button.
`label`	`string`	none
Visible label. Without a visible name, provide `aria-label` or `aria-labelledby`.
`hint`	`string`	none
Help text linked through `aria-describedby`.
`error`	`string`	none
Error message shown in place of the hint. Sets `aria-invalid` and is announced when it appears.
`placeholder`	`string`	none
Placeholder shown when the field is empty.
`size`	`ColorInputSize'sm' \| 'md' \| 'lg'`	`'md'`
Component size.
`compact`	`boolean`	`false`
Reduces the control height without changing text or icons.
`disabled`	`boolean`	`false`
Disables interaction.
`readonly`	`boolean`	`false`
Prevents typing and removes the picker. The field remains focusable.
`invalid`	`boolean`	`false`
Sets `aria-invalid` and the error style. Does not block form submission by itself.
`clearable`	`boolean`	`false`
Adds a button that empties the value.
`clearLabel`	`string`	none
Accessible name of the clear button. Defaults to the library dictionary.
`pickerButtonLabel`	`string`	none
Accessible name of the swatch button that opens the picker. Defaults to the library dictionary.
`placement`	`ColorInputPlacement'bottom' \| 'bottom-start' \| 'bottom-end' \| 'top' \| 'top-start' \| 'top-end'`	`'bottom-start'`
Preferred panel position relative to the field.
`v-model`	`string \| null`	`null`
Colour written in `format`, or `null` when the field is empty. Typed text updates it when the reader presses Enter or leaves the field.

Events

Event	Type
`clear`	`[]`
The value was cleared; the model is already reset.

Slots

Slot	Type
`value-end`	`{}`
Content before the clear button.

Types

Types used in the API tables. Import exported types from vectis-ui.

export type ColorSwatch = string | { color: string; label: string }

CSS variables

Token	Value
`--vectis-control-size-color-picker-checker`	`0.5rem`