DOCSEARCHbyAlgolia
Submit Docs

Coloris Documentation

repository·main·Indexed 20 days ago

https://github.com/mdbassit/coloris

A lightweight, zero-dependency JavaScript color picker (v0.25.0) that converts text inputs into color selection fields. Supports themes, opacity, multiple color formats, and accessibility labels. Includes guides on global configuration, instance simulation via setInstance, event handling, and programmatic control of thumbnails and picker state.

Tokens
2.3K
Snippets
7
Records
7
Agent score
20%

What's inside Coloris

  1. How to simulate multiple instances using setInstance

    main

    While Coloris uses a single physical picker instance, you can simulate multiple distinct configurations (e.g., different themes or swatches for different parts of your UI) using Coloris.setInstance(selector, options).

    This assigns configuration overrides to elements matching the provided CSS selector. Any options not explicitly set for an instance will inherit from the global configuration.

    Note: The following options cannot be set per-instance and must be set globally:

    • el
    • wrap
    • rtl
    • inline
    • defaultColor
    • a11y
    // Instance 1: Polaroid theme, dark mode, no alpha, and specific swatches
Coloris.setInstance('.instance1', {
  theme: 'polaroid',
  themeMode: 'dark',
  alpha: false,
  formatToggle: true,
  swatches: ['#264653', '#2a9d8f', '#e9c46a']
});

// Instance 2: Swatches only
Coloris.setInstance('.instance2', {
  swatchesOnly: true,
  swatches: ['#264653', '#2a9d8f', '#e9c46a']
});

  2. Install and use Coloris via CDN or local files

    main

    To use Coloris, include the CSS and JavaScript files in your HTML. You can download them locally or use a CDN.

    Local installation: Add coloris.min.css and coloris.min.js to your page.

    CDN installation:

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/mdbassit/Coloris@latest/dist/coloris.min.css"/>
<script src="https://cdn.jsdelivr.net/gh/mdbassit/Coloris@latest/dist/coloris.min.js"></script>

    Activation: Once the assets are loaded, simply add the data-coloris attribute to any text input field to convert it into a color picker.

    <link rel="stylesheet" href="coloris.min.css"/>
<script src="coloris.min.js"></script>

<input type="text" data-coloris>

  3. Handle Coloris events

    main

    Coloris triggers events on the last active input field bound to the picker. Additionally, a global coloris:pick event is dispatched on the document whenever a color is selected.

    Input-specific events:

    • open: The color picker is opened.
    • close: The color picker is closed.
    • input: A new color is selected.
    • change: The color picker is closed and the selected color has changed.

    Global event:

    Listen to coloris:pick on the document to react to color selections anywhere in the application.

    // Listen for the global pick event
document.addEventListener('coloris:pick', event => {
  console.log('New color', event.detail.color);
});

  4. Manually update thumbnails and close the picker

    main

    Update thumbnails programmatically

    If you update an input field's value via JavaScript, the color thumbnail will not update automatically. You must manually dispatch an input event:

    document.querySelector('#color-field').dispatchEvent(new Event('input', { bubbles: true }));

    Close the picker programmatically

    You can close the dialog using Coloris.close(). Passing true as an argument will also revert the color to its original value.

    // Close the dialog
Coloris.close();

// Close the dialog and revert the color to its original value
Coloris.close(true);

  5. Customize accessibility labels (a11y)

    main

    To translate or customize the labels used by screen readers, provide an a11y object within the global Coloris() configuration.

    Coloris({
  a11y: {
    open: 'Open color picker',
    close: 'Close color picker',
    clear: 'Clear the selected color',
    marker: 'Saturation: {s}. Brightness: {v}.',
    hueSlider: 'Hue slider',
    alphaSlider: 'Opacity slider',
    input: 'Color value field',
    format: 'Color format',
    swatch: 'Color swatch',
    instruction: 'Saturation and brightness selector. Use up, down, left and right arrow keys to select.'
  }
});

  6. Configure Coloris globally

    main

    You can configure the global behavior of Coloris by calling the Coloris() function with an options object. These options can be updated at runtime to change the picker's behavior immediately.

    Example: Activating dark mode and disabling alpha support:

    Coloris({
  themeMode: 'dark',
  alpha: false
});

  7. Reference: Coloris configuration options

    main

    The following options can be passed to Coloris() to customize the picker's appearance and behavior.

    Coloris({
  // CSS selector or HTMLElement for the picker's container. 
  // Container must have CSS position 'relative' or 'absolute'.
  parent: '.container',

  // Custom selector to bind the picker to (HTML input fields, HTMLElement, or array).
  el: '.color-field',

  // Wrap input fields in a div with a thumbnail and accessible button (default: true).
  // Only works with custom 'el' selector, not with [data-coloris].
  wrap: true,

  // Enable basic right-to-left support.
  rtl: false,

  // Available themes: 'default', 'large', 'polaroid', 'pill' (horizontal).
  theme: 'default',

  // Theme mode: 'light' (default), 'dark', or 'auto' (follows system preference).
  themeMode: 'light',

  // Margin in pixels between input fields and the dialog.
  margin: 2,

  // Preferred color string format: 'hex' (default), 'rgb', 'hsl', 'auto', or 'mixed'.
  format: 'hex',

  // Enable format toggle buttons in the dialog (forces format to 'auto').
  formatToggle: false,

  // Enable/disable alpha (opacity) support.
  alpha: true,

  // Always include alpha value even if opacity is 100%.
  forceAlpha: false,

  // Hide all widgets except swatches.
  swatchesOnly: false,

  // Focus the color value input when opened.
  focusInput: true,

  // Select and focus the color value input when opened.
  selectInput: false,

  // Show an optional clear button.
  clearButton: false,

  // Label for the clear button.
  clearLabel: 'Clear',

  // Show an optional close button.
  closeButton: false,

  // Label for the close button.
  closeLabel: 'Close',

  // Array of color swatches to display. If empty, swatches are disabled.
  swatches: ['#264653', '#2a9d8f'],

  // Use as an inline widget (always visible, positioned statically).
  inline: false,

  // Default color for inline mode.
  defaultColor: '#000000',

  // Callback function called when a new color is picked. 
  // Arguments: (color, input)
  onChange: (color, input) => undefined
});