add colorpicker docs and added it do docs.json

2026-08-05 19:03:18 +04:00 · 2026-08-04 17:29:17 +02:00
parent 52fe729781
commit 5cd391e51a
2 changed files with 200 additions and 0 deletions
@@ -0,0 +1,196 @@
+---
+title: Color picker
+summary: A color picker lets users pick a color from a gradient, a set of swatches, or by typing a value. Use it in theme settings, tag colors, and any field that stores a color.
+docs-libs: [coloris.js]
+description: Let users pick a color in a form.
+layout: '@layouts/DocsMdxLayout.astro'
+---
+import Example from '@components/Example.astro';
+import CdnImportPlugin from '@components/CdnImportPlugin.astro';
+import { Code } from 'astro:components';
+import { site } from '@shared/lib/site.ts';
+
+## Overview
+
+The color picker is a normal text input with the [Coloris](https://github.com/melloware/coloris-npm) plugin attached. Coloris wraps the field, adds a color button inside it, and opens a picker on click. The value stays in the input, so the field works in a form like any other.
+
+<Example>
+<input type="text" class="form-control d-block" id="colorpicker-overview" value="#066fd1" />
+</Example>
+
+## Installation
+
+Install Coloris with npm:
+
+```shell
+npm install @melloware/coloris
+```
+
+Or include it from a CDN. You need both the script and its stylesheet:
+
+<Code
+	lang="html"
+	code={`<link rel="stylesheet" href="${site.cdnUrl}/dist/libs/@melloware/coloris/dist/coloris.min.css" />
+<script src="${site.cdnUrl}/dist/libs/@melloware/coloris/dist/umd/coloris.min.js"></script>`}
+/>
+
+Tabler restyles the picker to match the rest of the interface. Those styles live in the vendors plugin, so include `tabler-vendors.css` as well:
+
+<CdnImportPlugin plugins={['vendors']} />
+
+## Usage
+
+### Basic field
+
+Add a text input with the `form-control` class, then attach Coloris to it with a selector.
+
+<Example codeOnly>
+<input type="text" class="form-control d-block" id="colorpicker" value="#066fd1" />
+</Example>
+
+```js
+document.addEventListener('DOMContentLoaded', function () {
+  Coloris({
+    el: '#colorpicker',
+    selectInput: false,
+  })
+})
+```
+
+`selectInput: false` stops the plugin from selecting the whole text when the field gets focus.
+
+### Color format
+
+Set `format` to choose what the input stores. Use `hex` when you save the value in a database, because it is short and easy to read.
+
+| Format | Value in the input |
+| --- | --- |
+| `hex` | `#066fd1` |
+| `rgb` | `rgb(6, 111, 209)` |
+| `hsl` | `hsl(209, 94%, 42%)` |
+| `mixed` | Hex when the color is solid, `rgba()` when it is not. |
+| `auto` | Guessed from the current value. |
+
+<Example>
+<input type="text" class="form-control d-block" id="colorpicker-rgb" value="rgb(66, 153, 225)" />
+</Example>
+
+### Alpha channel
+
+Alpha is off by default. Set `alpha: true` to add the opacity slider.
+
+<Example>
+<input type="text" class="form-control d-block" id="colorpicker-alpha" value="rgba(174, 62, 201, 0.5)" />
+</Example>
+
+```js
+Coloris({ el: '#colorpicker-alpha', alpha: true, format: 'mixed' })
+```
+
+### Swatches
+
+Pass a list of colors as `swatches`. They show under the picker as quick choices. Tabler theme colors work well here.
+
+<Example>
+<input type="text" class="form-control d-block" id="colorpicker-swatches" value="#4299e1" />
+</Example>
+
+```js
+Coloris({
+  el: '#colorpicker-swatches',
+  swatches: ['#066fd1', '#4299e1', '#4263eb', '#ae3ec9', '#d6336c', '#d63939'],
+})
+```
+
+To read the colors from the theme instead of writing them by hand, take them from the CSS variables:
+
+```js
+const swatches = ['--tblr-blue', '--tblr-azure', '--tblr-indigo'].map(function (prop) {
+  return getComputedStyle(document.body).getPropertyValue(prop)
+})
+```
+
+### Swatches only
+
+Set `swatchesOnly: true` to hide the gradient. Users can then pick only from your list. Use it when a design system allows a fixed set of colors.
+
+<Example>
+<input type="text" class="form-control d-block" id="colorpicker-swatches-only" value="#2fb344" />
+</Example>
+
+### Common options
+
+These are the options you will need most often. Coloris has more, and they are listed in its [documentation](https://github.com/melloware/coloris-npm#configuration).
+
+| Option | What it does |
+| --- | --- |
+| `el` | Selector of the field or fields to attach to. |
+| `format` | Value format: `hex`, `rgb`, `hsl`, `mixed`, or `auto`. |
+| `alpha` | Shows the opacity slider. Off by default. |
+| `swatches` | List of colors shown under the picker. |
+| `swatchesOnly` | Hides the gradient and leaves only the swatches. |
+| `selectInput` | Selects the text when the field gets focus. |
+| `formatToggle` | Lets users switch the format inside the picker. |
+| `clearButton` | Adds a button that clears the value. |
+| `closeButton` | Adds a close button to the picker. |
+| `themeMode` | `light`, `dark`, or `auto`. |
+| `inline` | Shows the picker on the page instead of in a popup. |
+
+### Read the picked color
+
+Coloris fires a `coloris:pick` event on every change. Use it to update a preview or to save the value.
+
+```js
+document.addEventListener('coloris:pick', function (event) {
+  console.log(event.detail.color)
+})
+```
+
+### Several fields with different options
+
+`Coloris()` sets the options for all fields it is attached to. When one field needs its own settings, register it with `setInstance()`.
+
+```js
+Coloris({ el: '.color-input', alpha: false, swatchesOnly: false, swatches: swatches })
+
+Coloris.setInstance('#brand-color', {
+  alpha: false,
+  swatchesOnly: true,
+  swatches: swatches,
+})
+```
+
+There is one picker for the whole page, and it is set up again every time it opens. Options you leave out of an instance keep the value from the field opened before it. Repeat the options that matter in every instance, as in the example above, so each field always opens the same way.
+
+## Examples
+
+### Field with a label
+
+Use the picker like any other form field: a label, the input, and a hint below it.
+
+<Example bg="surface-secondary" column>
+<div class="card"> <div class="card-body"> <div class="mb-0"> <label class="form-label" for="colorpicker-form">Brand color</label> <input type="text" class="form-control d-block" id="colorpicker-form" value="#d6336c" /> <small class="form-hint">This color is used for buttons and links.</small> </div> </div> </div>
+</Example>
+
+## Accessibility
+
+- Always add a `<label>` linked to the input with `for` and `id`. The color button alone does not say what the field is for.
+- Keep the text value visible. Users who cannot tell colors apart can still read and type the value.
+- Do not use the color as the only meaning. If a color marks a status, repeat the status in text.
+- The picker can be used with the keyboard, and the input accepts a typed value, so a mouse is never required.
+
+<script>{`
+window.addEventListener('load', function () {
+	if (typeof Coloris === 'undefined') return;
+
+	const swatches = ['--tblr-blue', '--tblr-azure', '--tblr-indigo', '--tblr-purple', '--tblr-pink', '--tblr-red', '--tblr-orange', '--tblr-green'].map(function (prop) {
+		return getComputedStyle(document.body).getPropertyValue(prop).trim();
+	});
+
+	Coloris({ el: '.form-control[id^="colorpicker"]', selectInput: false, format: 'hex', alpha: false, swatchesOnly: false, swatches: swatches });
+
+	Coloris.setInstance('#colorpicker-rgb', { format: 'rgb', alpha: false, swatchesOnly: false, swatches: swatches });
+	Coloris.setInstance('#colorpicker-alpha', { format: 'mixed', alpha: true, swatchesOnly: false, swatches: swatches });
+	Coloris.setInstance('#colorpicker-swatches-only', { format: 'hex', alpha: false, swatchesOnly: true, swatches: swatches });
+});
+`}</script>
@@ -342,6 +342,10 @@
 							"title": "Color check",
 							"url": "/ui/forms/form-color-check/"
 						},
+						{
+							"title": "Color picker",
+							"url": "/ui/forms/form-colorpicker/"
+						},
 						{
 							"title": "Form fieldset",
 							"url": "/ui/forms/form-fieldset/"