diff --git a/docs/content/ui/forms/color-picker.mdx b/docs/content/ui/forms/color-picker.mdx
index bcda9fb8d..f5339bc4a 100644
--- a/docs/content/ui/forms/color-picker.mdx
+++ b/docs/content/ui/forms/color-picker.mdx
@@ -7,6 +7,7 @@ related: [/ui/forms/elements, /ui/forms/color-check, /ui/plugins/date-picker]
source: core/scss/ui/forms/_colorpicker.scss
css-vars: colorpicker
sass-vars: colorpicker
+added-in: '1.7.0'
classnames:
component:
- class: colorpicker
@@ -179,10 +180,52 @@ The swatch follows `.form-control-sm` and `.form-control-lg`, and the field keep
Inside a modal or an offcanvas the panel is appended to that dialog instead of ``, so it opens above it and stays inside its focus trap. Escape closes the panel first, and the dialog on the next press.
+
+
+
+
+
+
+
Edit label
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Set `data-bs-container` to a selector when the panel has to live somewhere else, for example in a wrapper with its own stacking order.
+
### Dark mode
The panel is appended to ``, outside the cascade of the field, so the plugin copies the nearest `data-bs-theme` to it and follows later changes. Set `data-bs-colorpicker-theme` to force a theme for the panel alone.
+### Right-to-left
+
+Nothing to set up. In a page with `dir="rtl"` the swatch moves to the other end of the field, the gradient and the sliders are mirrored, and the arrow keys follow the direction of the text.
+
+### Use the color in CSS
+
+The plugin writes the picked color to the `--tblr-colorpicker-value` custom property on the `.colorpicker` wrapper, or on the trigger when it is a button. That is what paints the swatch, and your own styles can read it too. The property is removed while the field is empty.
+
+```css
+.my-label-preview {
+ background-color: var(--tblr-colorpicker-value, transparent);
+}
+```
+
+The element has to be inside the wrapper or the button to see the value. For anything else on the page, listen to the `change.bs.colorpicker` event, as in the live preview below.
+
## Examples
### Field with a label
@@ -203,6 +246,38 @@ Use the picker like any other form field: a label, the input, and a hint below i
+### Live preview
+
+Listen to `change.bs.colorpicker` on the field to use the color as it changes. Here the value becomes the primary color of the elements below.
+
+
+
+
+
+
+
+ Badge
+ Status
+
+
+
+
+```js
+const field = document.getElementById('colorpicker-live');
+const preview = document.getElementById('colorpicker-live-preview');
+
+field.addEventListener('change.bs.colorpicker', (event) => {
+ if (event.value) {
+ preview.style.setProperty('--tblr-primary', event.value);
+ } else {
+ preview.style.removeProperty('--tblr-primary');
+ }
+});
+```
+
## JavaScript
### Via data attributes
@@ -283,6 +358,19 @@ document.getElementById('my-color').addEventListener('change.bs.colorpicker', (e
- The panel is a `role="dialog"`. Tab from the field moves into it, the arrow keys move the handle in the gradient (Shift for bigger steps), the sliders are native range inputs, and Escape closes the panel and returns focus to the field.
- The panel closes on a click outside and when focus moves to something outside it, so keyboard users are never trapped.
+### Keyboard
+
+| Key | Where | What it does |
+| --- | --- | --- |
+| Tab | Field | Moves focus into the open panel. |
+| Tab | Last control in the panel | Closes the panel and returns focus to the field. |
+| Shift + Tab | First control in the panel | Returns focus to the field and keeps the panel open. |
+| Arrow keys | Handle in the gradient | Change saturation and brightness by 1. |
+| Shift + arrow keys | Handle in the gradient | Change saturation and brightness by 10. |
+| Arrow keys | Hue and opacity sliders | Move the slider, as in any range input. |
+| Enter or Space | Swatch | Picks that color. |
+| Escape | Anywhere | Closes the panel. Inside a modal, the modal stays open. |
+
## Migration from Coloris
Until version 1.6 the color picker was the [Coloris](https://github.com/melloware/coloris-npm) library, restyled in `tabler-vendors.css`. It still ships in `dist/libs` and keeps working, but it will be removed in 2.0. To move a field to the plugin:
@@ -291,3 +379,20 @@ Until version 1.6 the color picker was the [Coloris](https://github.com/mellowar
- Wrap the input in `.colorpicker` and add `data-bs-toggle="colorpicker"`.
- Move the options to `data-bs-*` attributes. `el` and `setInstance()` are gone, because every field has its own instance. `themeMode`, `rtl` and `margin` are handled by the theme and the text direction. `selectInput` has no equivalent. `format: 'mixed'` becomes `format="auto"`.
- Replace the `coloris:pick` listener with `change.bs.colorpicker` on the field, or with the native `input` event.
+
+
diff --git a/screenshots/pages/colorpicker.astro b/screenshots/pages/colorpicker.astro
new file mode 100644
index 000000000..0df6b3adb
--- /dev/null
+++ b/screenshots/pages/colorpicker.astro
@@ -0,0 +1,53 @@
+---
+// The Colorpicker plugin added in 1.7: a label form with the color field and
+// its panel open under it, opacity slider and format select included. The
+// panel is opened here rather than left to a focus the capture tool cannot
+// make, and the fake cursor rests on the handle in the gradient.
+import ScreenshotLayout from '../layouts/ScreenshotLayout.astro'
+import Card from '@ui/Card.astro'
+import CardBody from '@ui/CardBody.astro'
+import Colorpicker from '@ui/Colorpicker.astro'
+import FormGroup from '@ui/FormGroup.astro'
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+