{"id":28491625,"url":"https://github.com/kitschpatrol/tweakpane-plugin-color-plus","last_synced_at":"2026-01-21T04:01:23.251Z","repository":{"id":296330803,"uuid":"993009987","full_name":"kitschpatrol/tweakpane-plugin-color-plus","owner":"kitschpatrol","description":"Advanced color handling for Tweakpane.","archived":false,"fork":false,"pushed_at":"2025-11-04T06:34:16.000Z","size":1855,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-04T08:25:37.337Z","etag":null,"topics":["color","npm-package","tweakpane","tweakpane-plugin"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitschpatrol.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-30T04:15:27.000Z","updated_at":"2025-11-04T06:34:19.000Z","dependencies_parsed_at":"2025-06-09T05:32:03.172Z","dependency_job_id":null,"html_url":"https://github.com/kitschpatrol/tweakpane-plugin-color-plus","commit_stats":null,"previous_names":["kitschpatrol/tweakpane-plugin-color-plus"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/kitschpatrol/tweakpane-plugin-color-plus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Ftweakpane-plugin-color-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Ftweakpane-plugin-color-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Ftweakpane-plugin-color-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Ftweakpane-plugin-color-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitschpatrol","download_url":"https://codeload.github.com/kitschpatrol/tweakpane-plugin-color-plus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Ftweakpane-plugin-color-plus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28625926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T02:47:06.670Z","status":"ssl_error","status_checked_at":"2026-01-21T02:45:44.886Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["color","npm-package","tweakpane","tweakpane-plugin"],"created_at":"2025-06-08T08:07:55.290Z","updated_at":"2026-01-21T04:01:23.240Z","avatar_url":"https://github.com/kitschpatrol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +--\u003e\n\n\u003c!-- title --\u003e\n\n# tweakpane-plugin-color-plus\n\n\u003c!-- /title --\u003e\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/banner-dark.webp\"\u003e\n  \u003cimg alt=\"Svelte Tweakpane UI Banner\" src=\"./assets/banner-light.webp\"\u003e\n\u003c/picture\u003e\n\n\u003c!-- badges --\u003e\n\n[![NPM Package tweakpane-plugin-color-plus](https://img.shields.io/npm/v/tweakpane-plugin-color-plus.svg)](https://npmjs.com/package/tweakpane-plugin-color-plus)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c!-- /badges --\u003e\n\n\u003c!-- short-description --\u003e\n\n**Advanced color handling for Tweakpane.**\n\n\u003c!-- /short-description --\u003e\n\n\u003e [!WARNING]\n\u003e\n\u003e This Tweakpane plugin is a work in progress and is provided as a zero-versioned pre-release preview. Expect bugs and possible API / UI changes until the first 1.0.0 release.\n\n## Overview\n\nThe Color Plus plugin adds support for many additional color formats to the [Tweakpane](https://tweakpane.github.io/docs/) UI library.\n\nThe plugin supports all [CSS Color Module Level 4](https://drafts.csswg.org/css-color-4/) formats and color spaces, and adds support for controlling colors stored as tuples / arrays, as well as additional color object formats.\n\nCurrently, the plugin (almost) exactly matches the functionality, options, and control presentation of Tweakpane's [built-in color input](https://tweakpane.github.io/docs/input-bindings/#color) — just with support for additional parameter formats and types. This means it should work as a drop-in replacement in existing projects that need to support additional color formats, but it also means that the current UI is not necessarily well-suited to manipulating the wide-gamut colors that can now be represented.\n\nColor notations for perceptually-uniform color spaces like [`oklch`](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl) are supported, **but the current implementation clips all out-of-gamut colors to the `sRGB` color space**. Future versions of the plugin might implement additional UI and options tailored working with wide color targeting the P3 or Rec. 2020 gamuts.\n\nThe plugin was developed specifically for the benefit of [Svelte Tweakpane UI](https://kitschpatrol.com/svelte-tweakpane-ui) and [Tweakpane CSS](https://github.com/kitschpatrol/tweakpane-css), but there's no reason it can't be used in vanilla Tweakpane projects as well.\n\n## Getting started\n\n### Dependencies\n\nThe plugin requires [Tweakpane 4](https://www.npmjs.com/package/tweakpane).\n\nIf you're using the [\"lite\" build](#the-lite-plugin-build) of the plugin without a bundler, you'll need to provide the [@tweakpane/core](https://www.npmjs.com/package/@tweakpane/core) library as well.\n\nIf you're using Svelte 4 or 5 as a front-end library, you might want to take a look at [Svelte Tweakpane UI](https://kitschpatrol.com/svelte-tweakpane-ui), which wraps Tweakpane in a set of Svelte-friendly components, and integrates the Color Plus plugin as part of a preview release.\n\n### Installation\n\n#### NPM\n\n```sh\nnpm install tweakpane-plugin-color-plus\n```\n\n#### CDN\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/tweakpane-plugin-color-plus\"\u003e\u003c/script\u003e\n```\n\n### Usage\n\nImport and register the plugin. For now, you must explicitly add `view: 'color-plus'` to the `addBinding` options object. (Tweakpane's built-in color input handling will take precedence in the absence of the `view` option.)\n\n#### NPM\n\n\u003c!-- code { file: \"./demo/npm/index.js\" } --\u003e\n\n```js\nimport { Pane } from 'tweakpane'\nimport * as TweakpanePluginColorPlus from 'tweakpane-plugin-color-plus'\n\nconst params = {\n  color: 'oklch(65% 0.26 357deg)',\n}\n\nconst pane = new Pane()\n\npane.registerPlugin(TweakpanePluginColorPlus)\n\npane.addBinding(params, 'color', { view: 'color-plus' })\n\npane.on('change', () =\u003e {\n  document.documentElement.style.backgroundColor = params.color\n})\n```\n\n\u003c!-- /code --\u003e\n\n#### CDN\n\n\u003c!-- code { file: \"./demo/cdn/index.html\" } --\u003e\n\n```html\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003ctitle\u003eTweakpane Plugin Color Plus Demo\u003c/title\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" /\u003e\n    \u003cscript type=\"importmap\"\u003e\n      {\n        \"imports\": {\n          \"tweakpane\": \"https://cdn.jsdelivr.net/npm/tweakpane\",\n          \"tweakpane-plugin-color-plus\": \"https://cdn.jsdelivr.net/npm/tweakpane-plugin-color-plus\"\n        }\n      }\n    \u003c/script\u003e\n    \u003cscript type=\"module\"\u003e\n      import { Pane } from 'tweakpane'\n      import * as TweakpanePluginColorPlus from 'tweakpane-plugin-color-plus'\n\n      const params = {\n        color: 'oklch(65% 0.26 357deg)',\n      }\n\n      const pane = new Pane()\n      pane.registerPlugin(TweakpanePluginColorPlus)\n      pane.addBinding(params, 'color', { view: 'color-plus' })\n\n      pane.on('change', () =\u003e {\n        document.documentElement.style.backgroundColor = params.color\n      })\n    \u003c/script\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003c!-- /code --\u003e\n\n### Features\n\n### Color spaces\n\nAs a trade-off between bundle size and flexibility, Color Plus only supports \"predefined\" color spaces included in the CSS 4 color specification, with the sole addition of `HSV` for parity with the built-in Tweakpane color input implementation.\n\nSupported spaces / color functions include:\n\n- Adobe RGB (1998)\n- HSL\n- HSV _(for parity with Tweakpane's built-in color input)_\n- HWB\n- Lab D65\n- Lab _(a.k.a. Lab D50)_\n- LCH\n- Oklab\n- Oklch\n- Display P3\n- ProPhoto RGB\n- Rec. 2020\n- sRGB\n- sRGB Linear\n- XYZ D50\n- XYZ D65 _(a.k.a. XYZ)_\n\n### Color formats\n\nThe Color Plus plugin supports a wide range of parameter values formats beyond those of the built-in Tweakpane color input. The plugin \"remembers\" the original format of the input value, and will always transform any valid color input value entered in the text field of the Tweakpane UI widget into that format.\n\n#### String formats\n\nHexadecimal strings values with or without alpha components are supported:\n\n```ts\nconst hexStrings = {\n  hexString: '#ff0066',\n  hexStringAlpha: '#ff00667f',\n}\n```\n\n`0x`-prefixed hex strings like `'0xff0066'` are also supported, but will be normalized to `#`-prefixed representation.\n\nYou can input any CSS [`\u003cnamed-color\u003e`](https://developer.mozilla.org/en-US/docs/Web/CSS/named-color) string like `rebeccapurple` in the widget's text field, but these may not currently be used as initial parameter values, and will be converted to the widget's initial representation format. (Future versions might add additional support for named colors.)\n\n#### Number formats\n\nNumeric values with or without alpha components are supported:\n\n```ts\nconst numbers = {\n  number: 0xff_00_66,\n  numberAlpha: 0xff_00_66_7f,\n}\n```\n\nDecimal representations like `16711782` are also supported, but will be normalized to `0x`-prefixed representation in the widget's text field.\n\n#### Object formats\n\nThe Color Plus plugin should \"just work\" with a range of color object keys, including any combination of long keys like `red` and short keys like `r` and `g`.\n\nThe plugin will infer the desired representation from the keys.\n\nFloat values are supported via the `type: 'float'` binding parameter:\n\n```ts\nconst objects = {\n  object: { r: 255, g: 0, b: 102 },\n  objectAlpha: { r: 255, g: 0, b: 102, a: 0.5 },\n  objectFloat: { r: 1, g: 0, b: 0.4 },\n  objectFloatAlpha: { r: 1, g: 0, b: 0.4, a: 0.5 },\n  objectLongKeys: { red: 255, green: 0, blue: 102 },\n  objectLongKeysAlpha: { red: 255, green: 0, blue: 102, alpha: 0.5 },\n  objectMixedKeys: { r: 255, green: 0, b: 102 },\n  objectHsl: { h: 336, s: 100, l: 50 },\n  objectHsv: { h: 336, s: 100, v: 100 },\n  objectHwb: { h: 336, w: 0, b: 0 },\n  objectLab: { l: 55, a: 83, b: 21 },\n  objectLch: { l: 55, c: 85, h: 14 },\n}\n```\n\n#### Tuple / array formats\n\nTuple color representations can be useful for interoperability with libraries like [three.js](https://threejs.org/).\n\nNumeric tuple / array values with or without alpha components are supported. Alpha values must be between 0.0 and 1.0:\n\nFloat values are supported via the `type: 'float'` binding parameter:\n\n```ts\nconst tuples = {\n  tuple: [255, 0, 102],\n  tupleAlpha: [255, 0, 102, 0.5],\n  tupleFloat: [1, 0, 0.4],\n  tupleFloatAlpha: [1, 0, 0.4, 0.5],\n}\n```\n\n### Generic CSS `color()` function\n\nThe Color Plus plugin supports all [CSS 4 `color()` function strings](https://drafts.csswg.org/css-color-4/#funcdef-color) for the supported color spaces:\n\n```ts\nconst functions = {\n  colorA98Rgb: 'color(a98-rgb 0.86 0 0.39)',\n  colorDisplayP3: 'color(display-p3 0.92 0.2 0.41)',\n  colorHsl: 'color(hsl 336 100% 50%)',\n  colorHwb: 'color(hwb 336 0% 0%)',\n  colorLab: 'color(lab 55 66% 16%)',\n  colorLabD65: 'color(lab-d65 54 66% 15%)',\n  colorLch: 'color(lch 55 56% 4%)',\n  colorOklab: 'color(oklab 0.64 0.25 0.05)',\n  colorOklch: 'color(oklch 60% 0.24 13deg)',\n  colorPrefixHsv: 'color(--hsv 336deg 100% 100)',\n  colorProphotoRgb: 'color(prophoto-rgb 0.72 0.28 0.33)',\n  colorRec2020: 'color(rec2020 0.8 0.23 0.35)',\n  colorSrgb: 'color(srgb 1 0% 40%)',\n  colorSrgbLinear: 'color(srgb-linear 1 0 0.13)',\n  colorXyz: 'color(xyz 0.44 0.22 0.15)',\n  colorXyzD50: 'color(xyz-d50 0.46 0.23 0.11)',\n  colorXyzD65: 'color(xyz-d65 0.44 0.22 0.15)',\n}\n```\n\n### Space-specific functions\n\nYou may use the modern `/`-separated format for alpha components, or the legacy `,`-separated format.\n\n```ts\nconst functions = {\n  // hsl() strings (Tweakpane built-in)\n  funcHslLegacy: 'hsl(336, 100%, 50%)',\n  funcHsl: 'hsl(336 100% 50%)',\n  funcHslAlpha: 'hsl(336 100% 50% / 0.5)',\n  funcHslLegacyNoUnits: 'hsl(336, 100, 50)',\n  funcHslFancyUnits: 'hsl(336deg 100% 50% / .5)',\n\n  // hsla() strings (Tweakpane built-in)\n  funcHslaLegacy: 'hsla(336, 100%, 50%, 0.5)',\n  funcHsla: 'hsla(336 100% 50% / 0.5)',\n  funcHslaLegacyNoUnits: 'hsla(336, 100, 50, 0.5)',\n  funcHslaFancyUnits: 'hsla(336deg 100% 50% / 0.5)',\n\n  // hwb() strings\n  funcHwbLegacy: 'hwb(336, 0%, 0%)',\n  funcHwb: 'hwb(336 0% 0%)',\n  funcHwbAlpha: 'hwb(336 0% 0% / 0.5)',\n\n  // lab() strings\n  funcLabLegacy: 'lab(55%, 83, 21)',\n  funcLab: 'lab(55% 83 21)',\n  funcLabAlpha: 'lab(55% 83 21 / 0.5)',\n\n  // lch() strings\n  funcLchLegacy: 'lch(55, 85, 14)',\n  funcLch: 'lch(55 85 14)',\n  funcLchAlpha: 'lch(55 85 14 / 0.5)',\n\n  // oklab() strings\n  funcOklabLegacy: 'oklab(0.64, 0.25, 0.05)',\n  funcOklab: 'oklab(0.64 0.25 0.05)',\n  funcOklabAlpha: 'oklab(0.64 0.25 0.05 / 0.5)',\n\n  // oklch() strings\n  funcOklchLegacy: 'oklch(60%, 0.26, 11deg)',\n  funcOklch: 'oklch(60% 0.26 11deg)',\n  funcOklchAlpha: 'oklch(60% 0.26 11deg / 0.5)',\n\n  // rgb() strings (Tweakpane built-in)\n  funcRgbLegacy: 'rgb(255, 0, 102)',\n  funcRgb: 'rgb(255 0 102)',\n  funcRgbAlpha: 'rgb(255 0 102 / 0.5)',\n\n  // rgba() strings (Tweakpane built-in)\n  funcRgbaLegacy: 'rgba(255, 0, 102, 0.5)',\n  funcRgba: 'rgba(255 0 102 / 0.5)',\n}\n```\n\n### Implementation notes\n\n#### Tweakpane's built-in color handling\n\nThis plugin is largely derived from the core Tweakpane library's color input implementation — it (mostly) reuses the views and controllers, and only really makes significant changes to the model, where it replaces Tweakpane's bespoke color handling functionality with an implementation provided by the [Color.js](https://colorjs.io/) library.\n\n#### Color.js v0.6.x\n\nThe plugin uses Color.js' [procedural API](https://colorjs.io/docs/procedural) and [only imports a subset of available color spaces](#color-spaces) in the interest of performance and bundle size optimization.\n\n#### Other JavaScript color libraries\n\nI investigated a number of libraries to back the internal color representation in the Color Plus plugin. [Color.js](https://colorjs.io/) was selected because it offers \"round trip\" continuity of per-coordinate string formatting style, but there are a number of great libraries out there with robust support for modern color spaces and formats. Here are a few:\n\n- [ChromaJS](https://gka.github.io/chroma.js/) by [Gregor Aisch](https://driven-by-data.net/)\n\n- [Culori](https://culorijs.org/) by [Dan Burzo](http://danburzo.ro/)\n\n- [thi.ng/color](https://github.com/thi-ng/umbrella/tree/develop/packages/color#readme) by [Karsten Schmidt](https://mastodon.thi.ng/@toxi)\n\n#### The \"lite\" plugin build\n\nThe [Rollup](https://rollupjs.org) configuration provided in the [Tweakpane plugin template](https://github.com/tweakpane/plugin-template) does not externalize [`@tweakpane/core`](https://github.com/cocopon/tweakpane/tree/main/packages/core) as a production dependency.\n\nInstead, it gets built into the single-file plugin artifact, which is typically what's published to NPM and imported by plugin consumers. This makes it easy to import as an ES module from a URL, but means that larger projects importing multiple Tweakpane plugins end up with duplicate bundled copies of the `@tweakpane/core` code, adding about \\~100 Kb to the final minified build for each plugin after the first.\n\nTo avoid this size penalty, Color Plus includes a \"lite\" version of the build, which is configured to externalize the `@tweakpane/core` dependency. This allows multiple Tweakpane plugins to share a single instance of the `@tweakpane/core`. (I also maintain [forks of a number of popular Tweakpane plugins](https://kitschpatrol.com/svelte-tweakpane-ui/docs/plugins#bundled-plugins) with the `@tweakpane/core` dependency externalization optimization.)\n\nYou can import the \"lite\" version like this:\n\n```ts\nimport * as TweakpanePluginColorPlus from 'tweakpane-plugin-color-plus/lite'\n```\n\nIf you're not using a bundler, direct ESM imports from URLs can still work by defining the `@tweakpane/core` dependency manually in an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap).\n\nOr, if you're just using a single plugin and would rather not think about it, a \"classic\" all-inclusive build is exported by default to match the typical behavior of a Tweakpane plugin:\n\n```ts\nimport * as TweakpanePluginColorPlus from 'tweakpane-plugin-color-plus'\n```\n\nYou can see the effect of externalization on the minified library's size below:\n\n\u003c!-- size-table { files: [\"./dist/tweakpane-plugin-color-plus.min.js\", \"./dist/tweakpane-plugin-color-plus.lite.min.js\"] } --\u003e\n\n| File                                    | Original | Gzip    | Brotli  |\n| --------------------------------------- | -------- | ------- | ------- |\n| tweakpane-plugin-color-plus.min.js      | 192.3 kB | 49.9 kB | 41.6 kB |\n| tweakpane-plugin-color-plus.lite.min.js | 82.3 kB  | 27.9 kB | 24 kB   |\n\n\u003c!-- /size-table --\u003e\n\n## Maintainers\n\n[@kitschpatrol](https://github.com/kitschpatrol)\n\n## Acknowledgments\n\nThank you to [Hiroki Kokubun](https://cocopon.me) for creating and maintaining the excellent [Tweakpane](https://tweakpane.github.io/docs/) library.\n\nThanks also to [Lea Verou](http://lea.verou.me/) and [contributors](https://github.com/color-js/color.js/graphs/contributors) for creating the [Color.js](https://colorjs.io/) library.\n\n\u003c!-- footer --\u003e\n\n## Contributing\n\n[Issues](https://github.com/kitschpatrol/tweakpane-plugin-color-plus/issues) and pull requests are welcome.\n\n## License\n\n[MIT](license.txt) © Eric Mika\n\n\u003c!-- /footer --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Ftweakpane-plugin-color-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitschpatrol%2Ftweakpane-plugin-color-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Ftweakpane-plugin-color-plus/lists"}