ColorPlus

A color picker with support for additional color value formats.

Important: This component is still under development and should be considered experimental. The API is subject to breaking changes outside of the wider library's semver until the Svelte Tweakpane UI 2.0 release.

Wraps the color control from the Color Plus plugin.

This component looks very similar to the Tweakpane-native <Color> control, but it adds support for all CSS Color Module Level 4 color formats, named-color strings, color arrays / tuples, a wider range of color objects, and a revised color picker with support for wide-gamut color spaces.

Its API is a superset of Tweakpane's built-in color input, so <ColorPlus> can generally be used as a drop-in replacement for <Color>.

<ColorPlus> is a dynamic component. The alpha prop is available for number values, while the type prop is available for object and tuple / array values. Other props are shared by every supported value type.

The gamuts and gamutLabel defaults adapt to the initially bound color's model: sRGB-bound models get a simple sRGB picker, while wide and perceptual models get Display P3 boundaries and a gamut label. The text fields also open in a mode appropriate to that model.

<ColorPlus> might replace the <Color> control entirely in the next major version of svelte-tweakpane-ui. Please report any issues you encounter.

Usage outside of a <Pane> component will implicitly wrap the color picker in <Pane position="inline">.

---

Example

Demo

Code

ColorPlusExample.svelte

<script lang="ts">
  import { ColorPlus } from 'svelte-tweakpane-ui'

  let startColor = 'oklch(93.7% 0.199 105deg / 1)'
  let endColor = 'oklch(70.2% 0.322 328deg / 1)'
</script>

<ColorPlus bind:value={startColor} label="Start Color" />
<ColorPlus bind:value={endColor} label="End Color" />

<div class="demo" style:--a={startColor} style:--b={endColor}></div>

<style>
  .demo {
    aspect-ratio: 1;
    width: 100%;
    background: linear-gradient(to top, var(--a), var(--b));
  }
</style>

---

Props

Dynamic Props

This component has dynamic props, which means the available props can change depending on the value or type of other props.

Props contingent on certain conditions are annotated below with a dynamic flag, and include explanations of the “conditions” affecting the prop’s availability. More Info →

disabled optional
Description	Prevent interactivity and gray out the control.
Type	boolean
Default	false

theme optional
Description	Custom color scheme. If undefined, inherits default Tweakpane theme equivalent to ThemeUtils.presets.standard, or the theme set with setGlobalDefaultTheme().
Type	Theme
Default	undefined

label optional
Description	Text displayed next to control.
Type	string
Default	undefined

value bindablerequired
Description	The value to control. A color value to control. Use a CSS color or named-color string, a packed number, a three- or four-item RGB(A) tuple, or a supported RGB, HSL, HSV / HSB, HWB, Lab, or LCH object shape. The value's type determines whether the alpha or type prop is available.
Type	ColorPlusValue

userExpandable optional
Description	Allow users to interactively expand / contract the picker.
Type	boolean
Default	true

expanded bindableoptional
Description	Expand or collapse the input's picker.
Type	boolean
Default	false

picker optional
Description	The style of value "picker" to use in the input.
Type	'inline' | 'popup'
Default	'popup'

constrain optional
Description	Keep the color inside the widest gamut configured in gamuts. Picks on the palette plane snap to the in-gamut frontier, while slider moves, typed text, and externally bound values shed chroma (at constant lightness and hue) to fit. Set to false to allow out-of-gamut colors.
Type	boolean
Default	true

formatLocked optional
Description	Whether a valid color entered in the picker's text field is converted back to the bound value's original format. Set to false to let a typed value switch the binding's format to match what was typed, provided the new format has the same value type and shape. (Experimental!)
Type	boolean
Default	true

gamutLabel optional
Description	Draw the name of the narrowest configured gamut that holds the current color in the picker plane's bottom-left corner. The default adapts to the initially bound color's model.
Type	boolean
Default	false for sRGB-bound models; true for wide / perceptual models

gamutLines optional
Description	Which configured gamut boundaries are stroked over the picker plane. 'inner' draws the narrower gamuts' lines, 'outer' draws the widest gamut's line (otherwise redundant with the drawn plane's own edge), 'all' draws both, and 'none' hides every line.
Type	GamutLines
Default	'inner'

gamuts optional
Description	RGB gamuts whose boundaries the OKLCH picker draws, as an array of ids. Both colorjs ids and their CSS aliases are accepted: 'srgb', 'p3' / 'display-p3', 'a98rgb' / 'a98-rgb', 'rec2020', and 'prophoto' / 'prophoto-rgb'. The default adapts to the initially bound color's model.
Type	string[]
Default	['srgb'] for sRGB-bound models; ['srgb', 'p3'] for wide / perceptual models

paletteChannels optional
Description	Which OKLCH channels map to the picker plane's axes and the slider, as [X][Y]_[slider].
Type	PlaneLayout
Default	'CL_H'

paletteProjection optional
Description	How the picker plane projects the gamut volume onto its rectangle. 'okhsv' uses an OKHSV saturation / value projection on lightness × chroma layouts (the most similar to Tweakpane's built-in palette), falling back to 'stretch' behavior on other layouts. 'perceptual' keeps absolute OKLCH spacing, so the gamut sits as an irregular region within the plane. 'stretch' fills the plane with the widest gamut, row by row.
Type	PaletteProjection
Default	'okhsv'

swatchFallback optional
Description	How the swatch preview's fallback triangle forces an out-of-gamut color into sRGB. 'clip' clamps each channel to its range, matching what the browser paints on screen. 'css' applies the CSS Color 4 gamut-mapping algorithm (chroma reduction at constant lightness and hue), which can disagree with on-screen rendering. Only affects the swatch preview, never the color value itself.
Type	GamutMethod
Default	'clip'

textFields optional
Description	Show the color model drop-down and per-channel text inputs below the picker palette. Set to false to hide them for a more compact, pointer-only picker. (The alpha slider's text input, if present, is unaffected.)
Type	boolean
Default	true

alpha optionaldynamic
Description	Treat the number as carrying an alpha component in its lowest byte (e.g. 0xff00667f).
Type	boolean
Default	false
Conditions	Available when value is a number.

type optionaldynamic
Description	Whether coordinate channels are floats from 0.0 to 1.0, or integers in their native ranges (0 to 255 for RGB, 0 to 360 for hue, and so on). Alpha channels always use the 0.0 to 1.0 range.
Type	ColorType
Default	'int'
Conditions	Available when value is an object or value is a tuple / array.

---

Events

change
Description	Fires when value changes. This event is provided for advanced use cases. It's usually preferred to bind to the value prop instead. The event.details payload includes a copy of the value and an origin field to distinguish between user-interactive changes (internal) and changes resulting from programmatic manipulation of the value (external).
Extends	ValueChangeEvent
Type	ColorPlusChangeEvent