ColorPanel
An inline color panel with saturation and brightness controls, opacity, preset colors, RGB/HSL inputs, and screen color picking. Use ColorPicker when you need a popup.
Import
import { NsColorPanel } from '@ns/ui'
import type { ColorPanelInputMode, ColorPanelProps } from '@ns/ui'
Examples
Basic Usage
Bind a color with v-model. The panel stays visible in the page.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const color = ref('#409eff')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsColorPanel v-model="color" />
<code>Current color: {{ color }}</code>
</NsSpace>
</template>
Opacity
show-alpha displays an opacity slider and an A input. Hex output includes two opacity digits when the color is translucent.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const opaque = ref('#409eff')
const translucent = ref('#409eff80')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>showAlpha = false</span>
<NsColorPanel v-model="opaque" />
<code>{{ opaque }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>showAlpha = true</span>
<NsColorPanel v-model="translucent" show-alpha />
<code>{{ translucent }}</code>
</NsSpace>
</NsSpace>
</template>
Output Formats
color-format controls the emitted string format. Compare opaque and translucent hex, rgb, and hsl values below. Switching the panel's RGB/HSL inputs does not change its output format.
<script setup lang="ts">
import { reactive } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const cases = reactive([
{ label: 'hex', format: 'hex' as const, alpha: false, value: '#409eff' },
{ label: 'hex + alpha', format: 'hex' as const, alpha: true, value: '#409eff80' },
{ label: 'rgb', format: 'rgb' as const, alpha: false, value: 'rgb(64, 158, 255)' },
{ label: 'rgb + alpha', format: 'rgb' as const, alpha: true, value: 'rgba(64, 158, 255, 0.5)' },
{ label: 'hsl', format: 'hsl' as const, alpha: false, value: 'hsl(210, 100%, 63%)' },
{
label: 'hsl + alpha',
format: 'hsl' as const,
alpha: true,
value: 'hsla(210, 100%, 63%, 0.5)'
}
])
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsSpace v-for="item in cases" :key="item.label" direction="vertical" align="start">
<span>{{ item.label }}</span>
<NsColorPanel v-model="item.value" :color-format="item.format" :show-alpha="item.alpha" />
<code style="max-width: 280px; overflow-wrap: anywhere">{{ item.value }}</code>
</NsSpace>
</NsSpace>
</template>
Input Modes
input-mode selects RGB or HSL numeric inputs. The hex input remains visible. Input mode and color-format can be configured independently.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const rgbInputs = ref('hsl(120, 100%, 50%)')
const hslInputs = ref('rgb(0, 255, 0)')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>RGB inputs, HSL output</span>
<NsColorPanel v-model="rgbInputs" input-mode="rgb" color-format="hsl" />
<code>{{ rgbInputs }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>HSL inputs, RGB output</span>
<NsColorPanel v-model="hslInputs" input-mode="hsl" color-format="rgb" />
<code>{{ hslInputs }}</code>
</NsSpace>
</NsSpace>
</template>
Persisting Input Mode
Store the mode in the parent with v-model:input-mode to restore it when the panel mounts again. Without inputMode, colorFormat="hsl" starts with HSL inputs; other formats start with RGB.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace, NsSwitch } from '@ns/ui'
import type { ColorPanelInputMode } from '@ns/ui'
const color = ref('#67c23a')
const mode = ref<ColorPanelInputMode>('rgb')
const visible = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace align="center">
<NsSwitch v-model="visible" aria-label="Show color panel" />
<span>Show panel; current mode: {{ mode }}</span>
</NsSpace>
<NsColorPanel v-if="visible" v-model="color" v-model:input-mode="mode" />
<code>{{ color }}</code>
</NsSpace>
</template>
Preset Colors
Supply your own palette, or pass [] to hide the preset area. Presets are native buttons: focus one with Tab and select it with Enter or Space.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const brand = ref('#126b52')
const withoutPredefine = ref('#67c23a')
const palette = ['#126b52', '#409eff', '#e6a23c', '#f56c6c', '#909399', '#ffffff']
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>Brand palette</span>
<NsColorPanel v-model="brand" :predefine="palette" />
<code>{{ brand }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>predefine = []</span>
<NsColorPanel v-model="withoutPredefine" :predefine="[]" />
<code>{{ withoutPredefine }}</code>
</NsSpace>
</NsSpace>
</template>
Screen Color Picking
The eyedropper appears only when the browser supports screen color picking. A picked color keeps the panel's existing opacity. Canceling does not change the color. Set :eye-dropper="false" to disable the feature.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const enabled = ref('#409eff80')
const disabled = ref('#409eff80')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>eyeDropper = true</span>
<NsColorPanel v-model="enabled" show-alpha />
<code>{{ enabled }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>eyeDropper = false</span>
<NsColorPanel v-model="disabled" show-alpha :eye-dropper="false" />
<code>{{ disabled }}</code>
</NsSpace>
</NsSpace>
</template>
Border
bordered is enabled by default. Disable it to place the panel inside an existing container while retaining its internal layout.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const bordered = ref('#409eff')
const unbordered = ref('#67c23a')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>bordered = true</span>
<NsColorPanel v-model="bordered" />
<code>{{ bordered }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>bordered = false</span>
<NsColorPanel v-model="unbordered" :bordered="false" />
<code>{{ unbordered }}</code>
</NsSpace>
</NsSpace>
</template>
Disabled
Disabling the panel prevents interaction with the color area, sliders, presets, and inputs. Color events are not emitted.
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsColorPanel, NsSpace } from '@ns/ui'
const color = ref('#409eff80')
const disabled = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsCheckbox v-model="disabled">Disable panel</NsCheckbox>
<NsColorPanel v-model="color" show-alpha :disabled="disabled" />
<code>{{ color }}</code>
</NsSpace>
</template>
Custom Width
The default width is 280px. Set style to resize the panel; its color area, sliders, and numeric inputs resize with it.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const narrow = ref('#409eff80')
const wide = ref('#67c23a80')
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsSpace direction="vertical" align="start">
<span>240px</span>
<NsColorPanel v-model="narrow" show-alpha style="width: 240px" />
<code>{{ narrow }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>360px</span>
<NsColorPanel v-model="wide" show-alpha style="width: 360px" />
<code>{{ wide }}</code>
</NsSpace>
</NsSpace>
</template>
In a Form
The panel follows the form's disabled state. By default, it triggers validation when the bound value changes or focus leaves the entire panel. Moving focus inside the panel does not trigger blur validation. :validate-event="false" disables automatic validation; the form's validate() method still checks the field.
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsColorPanel, NsForm, NsFormItem, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const form = ref<InstanceType<typeof NsForm>>()
const model = reactive({ automatic: '', manual: '' })
const rules: Record<string, FormRule[]> = {
automatic: [{ required: true, message: 'Choose a primary color', trigger: ['blur', 'change'] }],
manual: [{ required: true, message: 'Choose a secondary color', trigger: ['blur', 'change'] }]
}
const result = ref('Not validated')
const validate = async () => {
const checked = await form.value?.validate()
result.value = checked?.valid ? 'Validation passed' : 'Choose both required colors'
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsForm ref="form" :model="model" :rules="rules" label-position="top">
<NsSpace wrap align="start" :size="24">
<NsFormItem label="Primary: automatic validation" prop="automatic">
<NsColorPanel v-model="model.automatic" />
</NsFormItem>
<NsFormItem label="Secondary: manual validation only" prop="manual">
<NsColorPanel v-model="model.manual" :validate-event="false" />
</NsFormItem>
</NsSpace>
</NsForm>
<NsSpace align="center">
<NsButton type="primary" icon="check" @click="validate">Validate form</NsButton>
<span>{{ result }}</span>
</NsSpace>
</NsSpace>
</template>
Events
Dragging emits active-change continuously. update:modelValue and change are emitted on release. Selecting a preset, using the arrow keys, or completing an input also commits a color. This example displays the active value on the page and shows a message only when a color is committed.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsMessage, NsSpace } from '@ns/ui'
import type { ColorPanelInputMode } from '@ns/ui'
const color = ref('#409eff')
const mode = ref<ColorPanelInputMode>('rgb')
const active = ref('No active change')
const committed = ref('No committed color')
const updates = ref(0)
const handleUpdate = () => {
updates.value++
}
const handleChange = (value: string) => {
committed.value = value
NsMessage.success(`Selected color: ${value}`)
}
const handleActive = (value: string) => {
active.value = value
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsColorPanel
v-model="color"
v-model:input-mode="mode"
@update:model-value="handleUpdate"
@change="handleChange"
@active-change="handleActive"
/>
<span>update:modelValue: {{ updates }}; bound value: {{ color }}</span>
<span>activeChange: {{ active }}</span>
<span>change: {{ committed }}</span>
<span>update:inputMode: {{ mode }}</span>
</NsSpace>
</template>
Empty and Invalid Values
undefined, null, an empty string, or an unrecognized color starts the panel internally at #409EFF without writing it back. The bound values below remain unchanged until a color is selected.
<script setup lang="ts">
import { reactive } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const colors = reactive<Record<string, string | null | undefined>>({
undefined: undefined,
null: null,
'Empty string': '',
Invalid: 'not-a-color'
})
const display = (value: string | null | undefined) =>
value === undefined ? 'undefined' : JSON.stringify(value)
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsSpace v-for="(value, name) in colors" :key="name" direction="vertical" align="start">
<span>{{ name }}</span>
<NsColorPanel v-model="colors[name]" />
<code>Bound value: {{ display(value) }}</code>
</NsSpace>
</NsSpace>
</template>
With ColorPicker
The inline panel, popup picker, and preview share one bound value, as they would on a theme settings page.
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsColorPicker, NsSpace } from '@ns/ui'
const color = ref('#126b52')
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsColorPanel v-model="color" />
<NsSpace direction="vertical" align="start">
<NsSpace align="center">
<span>Theme color</span>
<NsColorPicker v-model="color" />
<code>{{ color }}</code>
</NsSpace>
<article class="color-preview" :style="{ borderTopColor: color }">
<h3>Quarterly Project Report</h3>
<p>Development progress and delivery schedule</p>
<div class="color-preview__sample" :style="{ backgroundColor: color }"></div>
<span>Theme color preview</span>
</article>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.color-preview {
width: 280px;
max-width: 100%;
padding: var(--ns-spacing-4);
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-top-width: 4px;
border-radius: var(--ns-border-radius);
color: var(--ns-text-color);
background: var(--ns-bg-color);
box-sizing: border-box;
}
.color-preview h3 {
margin: 0 0 var(--ns-spacing-2);
font-size: var(--ns-font-size-lg);
}
.color-preview p {
margin: 0 0 var(--ns-spacing-4);
color: var(--ns-text-color-secondary);
}
.color-preview__sample {
height: 12px;
margin-bottom: var(--ns-spacing-2);
border-radius: var(--ns-border-radius-sm);
}
</style>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| modelValue | string | null | undefined | undefined | Bound color. Empty or invalid values start the panel internally at #409EFF without writing it back |
| disabled | boolean | false | Disables the panel; also follows its parent form |
| showAlpha | boolean | false | Enables the opacity slider, A input, and output with opacity |
| colorFormat | 'hex' | 'rgb' | 'hsl' | 'hex' | Format of emitted color strings |
| predefine | string[] | 20 built-in colors | Preset colors. Pass [] to hide this area |
| eyeDropper | boolean | true | Enables screen color picking. The button is hidden when unsupported |
| inputMode | 'rgb' | 'hsl' | Follows colorFormat | Numeric input mode; supports v-model:input-mode. Defaults to HSL for colorFormat='hsl', otherwise RGB |
| bordered | boolean | true | Displays the outer border, rounded corners, and background |
| validateEvent | boolean | true | Triggers form validation when the bound value changes or focus leaves the panel |
Events
| Event | Callback | Description |
|---|---|---|
| update:modelValue | (value: string) | Emitted when a color is selected; dragging commits on release |
| change | (value: string) | Emitted together with update:modelValue |
| activeChange | (value: string) | Emitted continuously while dragging, and when a color is committed |
| update:inputMode | (mode: ColorPanelInputMode) | Emitted when the RGB/HSL mode button is clicked |
A color commit emits update:modelValue, change, and activeChange in that order. Use @update:model-value, @change, @active-change, and @update:input-mode in templates.
Slots
None.
Methods
No public methods.
Types
import type {
ColorPanelEmits,
ColorPanelInputMode,
ColorPanelProps,
ColorPickerFormat
} from '@ns/ui'
ColorPanelInputMode is 'rgb' | 'hsl'. ColorPanelProps.colorFormat uses ColorPickerFormat. ColorPanelProps and ColorPanelEmits are the public prop and event types.
Notes
- Supports
#rgb,#rgba,#rrggbb,#rrggbbaa,rgb(),rgba(),hsl(), andhsla(). Color names, CSS variables, HSB, and OKLCH are not supported. - Empty or unrecognized initial or external values start the panel internally at
#409EFF. They do not throw an error, write back a default, or emit color events during mounting or synchronization. - Hex output is lowercase. HSL hue, saturation, and lightness are rounded to integers, so conversions can introduce rounding differences.
inputModeaffects only numeric inputs. The hex input remains visible, andcolorFormatcontrols the emitted format. Switching RGB/HSL alone does not commit a color.- Numeric channels are clamped to their ranges. Empty or invalid numbers restore their previous values. A hue of 360 is treated as 0. Gray and black have no meaningful hue, so the hue slider keeps its current position for those colors.
- The eyedropper appears only when the browser provides screen color picking. It preserves opacity; canceling leaves the color unchanged. Results from an earlier picking operation are ignored after disabling the panel, changing its external color, or unmounting it.
- While picking, pressing the eyedropper again has no effect. The button is dimmed and remains focusable.
- Arrow keys adjust the color area, hue, and opacity. Hold Shift for larger steps. Preset colors, the eyedropper, and the input mode button are keyboard accessible.
- The panel is 280px wide by default. Set
styleto resize it; its maximum width is constrained by its parent. Use ColorPicker for a popup trigger with focus cycling.