jb-color-input

jb-color-input is a form-associated CSS color input. It combines the label, message, validation, form, and size behavior of jb-input with jb-color-picker in a popover.

• Accepts RGB, hexadecimal, and OKLCH CSS colors.
• Provides editable color text and a visual picker.
• Supports RGB and OKLCH color spaces.
• Supports optional alpha controls.
• Supports ArrowUp and ArrowDown changes for the color parameter at the caret.
• Supports required and CSS-color validation.
• Supports native HTML form submission and reset.
• Supports xs, sm, md, lg, and xl sizes.
• Supports TypeScript and React.
• Supports custom styling with CSS variables and CSS parts.

When to use

Use jb-color-input when users need to type or visually select a color and the value must participate in a form, validation flow, or standard input layout.

Use jb-color-picker when you need only an embeddable picker surface without a text field, popover, form association, or validation.

Demo

• Interactive Storybook demo
• Size variants
• Disabled state
• Invalid color validation

Using with JS frameworks

See the React documentation.

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

npm i jb-color-input

import "jb-color-input";

<jb-color-input label="Brand color" name="brandColor" value="#3b66f5"></jb-color-input>

CDN

Use an ESM CDN so package dependencies are resolved automatically.

<script type="module">
  import "https://esm.sh/jb-color-input";
</script>

API reference

jb-color-input extends jb-input. The color-specific API is listed below; label, message, placeholder, form, validation, focus, selection, and standard input behavior come from the jb-input API.

Color attributes

| name | type | default | description | | --- | --- | --- | --- | | color-space | "rgb" \| "oklch" | none | Locks the embedded picker to one color space. Omit it to allow switching. Demo | | alpha-disabled | boolean | false | Hides the picker's alpha controls. Demo |

Common inherited attributes

| name | type | default | description | | --- | --- | --- | --- | | value | string | "" | Initial CSS color text. Prefer the property for runtime updates. | | label | string | "" | Visible and accessible field label. | | message | string | "" | Helper text shown below the input. | | name | string | "" | Form field name used during submission. | | placeholder | string | "" | Placeholder forwarded to the native text input. | | required | boolean \| string | false | Enables required validation; a string supplies a custom message. Demo | | disabled | boolean | false | Disables the text input, color trigger, and embedded picker. Demo | | error | string | "" | External validation message. | | size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | md style defaults | Sets the input and color-trigger size. Demo |

Color properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | string | no | Current CSS color text and native form value. | | valueObject | JBColorPickerValue \| null | yes | Parsed RGB/OKLCH object, or null when the text is empty or invalid. | | colorSpace | "rgb" \| "oklch" \| null | no | Locks the picker when set to a space. Set null to show its switch. | | alphaEnabled | boolean | no | Shows or hides picker alpha controls. | | isOpen | boolean | no | Opens or closes the picker popover. Disabled inputs cannot open it. | | colorInputElements | ColorInputElements | no | References to the trigger, preview, picker, and popover for advanced integrations. |

Inherited properties include initialValue, validation, disabled, required, isDirty, selection properties, and validationMessage.

Methods

| name | returns | description | | --- | --- | --- | | openPicker() | void | Opens the picker unless the input is disabled. Demo | | closePicker() | void | Closes the picker. Demo | | checkValidity() | boolean | Checks required, CSS-color, and custom validation without showing an error. | | reportValidity() | boolean | Checks validity and displays the first error. Demo | | focus() | void | Focuses the native input; focus opens the picker when enabled. | | setSelectionRange(start, end, direction?) | void | Changes the native input selection. |

Value and color spaces

The field stores and submits CSS color text. Supported values include modern or comma-separated rgb()/rgba(), oklch(), and 3-, 4-, 6-, or 8-digit hexadecimal colors.

const input = document.querySelector("jb-color-input");

input.value = "#3b66f5cc";
console.log(input.valueObject);
// { colorSpace: "rgb", r: 59, g: 102, b: 245, alpha: 0.8... }

Typed text remains in the form the user entered. Selecting through the picker updates value to a normalized rgb() or oklch() string.

Set color-space="rgb" or color-space="oklch" to lock the visual picker. This does not reject valid text written in the other supported syntax; valueObject reflects the parsed text while the picker converts it for display.

Keyboard parameter changes

Place the caret within a numeric color parameter and press ArrowUp or ArrowDown to change it. RGB channels and hue step by 1, alpha steps by 0.1, OKLCH lightness steps by 0.01, and OKLCH chroma steps by 0.001. Values are normalized to their supported ranges. Demo

Escape closes an open picker and returns focus to the color trigger.

Validation and forms

The field is valid when empty unless required is set. Non-empty text must be a supported CSS color; otherwise the component reports a badInput validation error. See the invalid-color demo.

<form>
  <jb-color-input label="Brand color" name="brandColor" required></jb-color-input>
  <button type="submit">Save</button>
</form>

The submitted value is the CSS string in .value. Form reset restores initialValue and closes the picker.

Events

jb-color-input uses the standard jb-input event contract.

| event | when it fires | value access | | --- | --- | --- | | input | On every text edit, picker update, or Arrow-key parameter change. | event.target.value | | change | When text is committed or the picker commits a change. | event.target.value | | beforeinput | Before native text input changes. | event.target.value | | focus / blur | When the input receives or loses focus. | event.target.value | | keydown / keyup | Re-dispatched from the native input. | event.target.value | | enter | When Enter is released. | event.target.value | | invalid | When a validity check fails. | event.target.validationMessage |

input.addEventListener("input", event => {
  console.log(event.target.value, event.target.valueObject);
});

Slots

The inherited start-section and end-section slots remain available. The color trigger is rendered alongside end-section content. See the jb-input slot documentation.

CSS variables

jb-input variables style the shared field shell, while jb-color-picker variables style the popover picker.

| variable | description | | --- | --- | | --jb-color-input-trigger-padding | Space inside the color trigger. Size-specific defaults are provided. | | --jb-color-input-trigger-size | Trigger width and height. Defaults to the input height minus padding. | | --jb-color-input-trigger-border-radius | Trigger border radius. | | --jb-color-input-preview-padding | Space between the trigger and color preview. | | --jb-color-input-preview-size | Preview width and height. | | --jb-color-input-preview-border-radius | Preview border radius. | | --jb-color-input-preview-border | Preview swatch border. | | --jb-color-input-corner-shape | Trigger/preview corner shape; falls back to --jb-input-corner-shape. | | --jb-color-input-popover-z-index | Picker popover stacking level. Defaults to 1000. | | --jb-color-input-focus-ring-color | Keyboard focus-ring color for the trigger. |

jb-color-input {
  --jb-color-input-preview-border: 2px solid currentColor;
  --jb-color-input-popover-z-index: 1200;
  --jb-color-picker-width: 20rem;
}

CSS parts and states

| part | description | | --- | --- | | color-trigger | Button that opens the picker. | | color-preview | Checkerboard-backed selected-color swatch. | | popover | jb-popover host. | | popover-content | Exported popover content wrapper. | | color-picker | Embedded jb-color-picker. |

The inherited label, input-box, input, and message parts and the disabled and invalid custom states also apply.

Accessibility notes

• The trigger is a button labeled “Open color picker” with aria-haspopup="dialog" and synchronized aria-expanded.
• The color preview is decorative and hidden from accessibility APIs.
• Focusing the text input opens the picker; Escape closes it and focuses the trigger.
• Focus can move between the input, trigger, popover, and picker without closing the popover. Moving outside closes it.
• Disabled state reaches the native input, trigger, and embedded picker.
• Form, label, message, and validation semantics are inherited from jb-input.

Related docs

• See jb-color-input/react for React usage.
• See jb-color-picker for the standalone picker API.
• See jb-input for inherited input behavior and styling.
• See all JB Design System components.
• Use the contribution guide to contribute.

AI agent notes

• Import jb-color-input once before rendering <jb-color-input>.
• Read and write .value as CSS color text; read .valueObject for parsed RGB or OKLCH data.
• valueObject can be null because users may temporarily type empty or invalid text.
• Use color-space and alpha-disabled in HTML; use colorSpace and alphaEnabled in JavaScript or React.
• The component is form-associated and inherits most input behavior from jb-input.
• Use the actual size attribute or React prop for xs, sm, md, lg, and xl variants.