Color Picker Component - API Reference

Key Features

Fully Accessible

WCAG 2.1 AA compliant with full keyboard navigation and screen reader support

Contrast Checking

Built-in WCAG contrast calculator with AA/AAA compliance indicators

Smart Suggestions

Automatically suggests accessible alternatives when colors fail contrast

Multiple Palettes

Pre-built accessible palettes: Default, Semantic, Grayscale, Rainbow

HSL Sliders

Fine-tune colors with intuitive Hue, Saturation, and Lightness controls

Eyedropper API

Pick colors from anywhere on screen using native browser eyedropper

Quick Start

Step 1: Include the CSS and JavaScript files:

<link rel="stylesheet" href="styles/color-picker.css">
<script src="javascript/color-picker.js"></script>

Step 2: Add the data attribute to any input element:

<!-- Basic color picker -->
<input type="text" data-rsl-color-picker>

<!-- With initial value and contrast checking -->
<input type="text"
       data-rsl-color-picker
       data-value="#6E7BFF"
       data-show-contrast="true"
       data-contrast-against="#FFFFFF">

<!-- Constrained mode (only accessible colors) -->
<input type="text"
       data-rsl-color-picker
       data-mode="constrained"
       data-min-contrast="4.5">

Data Attributes API

Attribute	Type	Default	Description
`data-rsl-color-picker`	-	-	Required. Initializes the color picker
`data-mode`	string	"palette"	Selection mode: "palette", "custom", or "constrained"
`data-format`	string	"hex"	Output format: "hex", "rgb", or "hsl"
`data-value`	string	null	Initial color value (hex format)
`data-palette`	string	"default"	Palette: "default", "semantic", "grayscale", "rainbow", "minimal"
`data-custom-palette`	JSON	-	Custom palette as JSON array
`data-contrast-against`	string	"#FFFFFF"	Background color to calculate contrast against
`data-min-contrast`	number	4.5	Minimum contrast ratio (4.5 = AA, 7 = AAA)
`data-wcag-level`	string	"AA"	WCAG compliance level: "AA" or "AAA"
`data-show-contrast`	boolean	true	Show contrast ratio and WCAG badges
`data-show-preview`	boolean	true	Show text/background preview
`data-show-names`	boolean	true	Include color names for screen readers
`data-show-recent`	boolean	true	Show recently used colors
`data-show-alpha`	boolean	false	Enable opacity/alpha slider
`data-close-on-select`	boolean	false	Close picker immediately when a color is selected (vs requiring Apply button)
`data-inline`	boolean	false	Display picker inline (always visible)
`data-compact`	boolean	false	Compact trigger (swatch only, no text)
`data-disabled`	boolean	false	Disable the color picker
`data-required`	boolean	false	Mark as required for form validation
`data-aria-label`	string	"Color picker"	Accessibility label for screen readers

JavaScript API

Method	Parameters	Returns	Description
`init()`	-	this	Initialize all color pickers on the page
`create(element, options)`	element, options	instance	Create a color picker on a specific element
`getInstance(element)`	element	instance	Get the instance for an element
`getValue(instance)`	instance	object	Get current value as {hex, rgb, hsl, alpha}
`setValue(instance, color)`	instance, color	-	Set the color value
`open(instance)`	instance	-	Open the color picker dialog
`close(instance)`	instance	-	Close the color picker dialog
`getContrastRatio(fg, bg)`	fg, bg (hex)	number	Calculate WCAG contrast ratio between two colors
`getWCAGStatus(ratio)`	ratio	object	Get WCAG pass/fail status for a ratio
`suggestAccessibleColor(color, against, target)`	color, against, targetRatio	string	Suggest an accessible alternative color

Pro Tip: The getContrastRatio() and suggestAccessibleColor() methods can be used independently for any accessibility checking in your application!

Events

Event	Detail Properties	Description
`change`	hex, rgb, hsl, contrast, wcag	Fired when a color is applied

document.querySelector('.rsl-color-picker').addEventListener('change', function(e) {
    console.log('Selected color:', e.detail.hex);
    console.log('Contrast ratio:', e.detail.contrast.toFixed(2));
    console.log('Passes AA:', e.detail.wcag.normalAA);
});

Accessibility

The RSL Color Picker is designed from the ground up for accessibility:

Full Keyboard Navigation: Tab between elements, Arrow keys to navigate swatches, Enter/Space to select
Screen Reader Support: Color names, hex values, and contrast ratios are announced
ARIA Compliance: Proper roles (dialog, listbox, option), aria-selected, aria-expanded
Focus Management: Focus trap in dialog, returns to trigger on close
Live Regions: Contrast status changes announced via aria-live
Large Touch Targets: 48x48px minimum for all interactive elements
Reduced Motion: Respects prefers-reduced-motion preference
Color-Independent: Contrast info shown as text, not just color badges

Next Steps

See Examples

View examples.html for comprehensive demos

Try the Playground

Test features in playground.html

Explore Components

Browse all RSL components

Color Picker PREMIUM