Bootstrap Color Palette

No color selected

Installation

BCP requires jQuery v1.9.1+, Bootstrap 4 popover component, and Bootstrap's CSS.

Just make sure to import required dependencies, then library's core files.
If you don't include the optional default palette, you'll need to define your own to make the plugin work.

Several installation methods are available:

• With npm or yarn
  npm i bootstrap-color-palette
yarn add bootstrap-color-palette
  Then require the plugin and a palette:

  require('bootstrap-color-palette/dist/bcp');
  require('bootstrap-color-palette/dist/bcp.en');

• Via CDN
  Core script: https://cdn.jsdelivr.net/gh/bgaze/bootstrap-color-palette@1/dist/bcp.min.js
  Core CSS: https://cdn.jsdelivr.net/gh/bgaze/bootstrap-color-palette@1/dist/bcp.min.css
  Default palette (english): https://cdn.jsdelivr.net/gh/bgaze/bootstrap-color-palette@1/dist/bcp.en.min.js
  Default palette (french): https://cdn.jsdelivr.net/gh/bgaze/bootstrap-color-palette@1/dist/bcp.fr.min.js
• From Github
  Download the latest release: https://github.com/bgaze/bootstrap-color-palette/releases
  Or clone the repo: git clone https://github.com/bgaze/bootstrap-color-palette.git

Usage

Quick start

• Use data-color attribute via Javascript or HTML to define component initial color.
• Use pcb.refresh event to manage impact on your application appearance.
  You should define this callback before instantiating the component to make sure it is called on page load.
• Use pcb.selected event to define your callback on color change.
  It's the good place to manage BCP impact on your application appearance.
• Use bcp jQuery plugin to instantiate your component(s).
  You can pass a set of options to override global configuration.
• The color method allows to set/get programmatically a component color.

Here is a detailed example of BCP usage:

$('[data-toggle="bcp"]')
    .attr('data-color', '#000')
    .on('pcb.refresh', function () {
        let color = $(this).bcp('color');

        if (color) {
            $(this)
                .text(color.label)
                .css({
                    backgroundColor: color.value,
                    color: color.dark ? '#fff' : '#000'
                });
        }
    })
    .on('pcb.selected', function () {
        $.post('my/endpoint/url', {data: $(this).bcp('color')});
    })
    .bcp({
        placement: 'right'
    });

Options

You can use any popover option, via data attributes or JavaScript, except following ones that are reserved : html, sanitize, trigger, content.
The plugin itself offers several options:

<div class="popover bcp-popover" role="tooltip">
    <div class="arrow"></div>
    <h3 class="popover-header"></h3>
    <div class="popover-body"></div>
</div>

function (colors) {
    var content = `<div class="bcp-content">`;

    for (let row of colors) {
        content += `<div class="bcp-row">`;
        for (var color in row) {
            let className = isColorDark(color) ? 'dark' : 'light';
            content += `<div class="bcp-color ${className}"
                             style="background-color: ${color};"
                             data-color="${color}"
                             title="${row[color]}"
                             ></div>`;
        }
        content += `</div>`;
    }

    content += `</div>`;

    return content;
}

Methods

You can use any of Bootstrap popover methods on a BCP element.
The plugin itself provides the color method which allow to set / get the color of a component:

// Set the color of a component (hexadecimal format expected).
$('.my-bcp-element').bcp('color', '#ffff00');

// Get the color of a component.
$('.my-bcp-element').bcp('color');

In get mode, color will be returned as an object:

{
    value: '#ffff00', // The hex code of the color
    label: 'Red',     // The label of the color
    dark: false       // Whether the color is dark
}

The dark information helps to ensure that foreground and background color combinations provide sufficient contrast.
It's useful when viewed by someone having color deficits or when viewed on a black and white screen.
See https://www.w3.org/TR/AERT/#color-contrast for more informations.

Events

You can use any of Bootstrap popover events on a BCP element.
The plugin itself provides following events:

pcb.refresh:

This event is fired when the BCP component is instantiated and when it's color changes.
It's the good place to manage BCP impact on your application appearance.

$('.my-bcp-element').on('pcb.refresh', function (e) {
    let color = $(this).bcp('color');
    if (color) {
        $(this).css({
            backgroundColor: color.value,
            borderColor: color.value,
            color: color.dark ? '#fff' : '#000'
        });
    }
});

pcb.selected:

This event is fired when a color is selected in a BCP component.
It's the good place to manage the application logic.

$('.my-bcp-element').on('pcb.selected', function (e) {
    $.post('my-url/', $(this).bcp('color'));
});

Custom palette

You can easily define your own color palette for your BCP components.
It is represented as an array of objects:

• Each object represent a row in the palette.
• Each key-value couple in a row represent a color: hex code as key and label as value.

$('#palette-demo').bcp({
    colors: [
        {
            "#e6b8af": "Red",
            "#fff2cc": "Yellow"
        },
        {
            "#d9ead3": "Green",
            "#c9daf8": "Blue"
        }
    ]
});

Try it

Global configuration

BCP can be configured globally using the $.bcpSetup helper.
In addition to BCP options, any non-reserved popover option is accepted.

$.bcpSetup({
    placement: 'left',
    colors: [
        {
            "#e6b8af": "Red",
            "#fff2cc": "Yellow"
        },
        {
            "#d9ead3": "Green",
            "#c9daf8": "Blue"
        }
    ]
});

Styling

BCP inserts several classes prefixed with bcp- to ease component styling.

As an example, here is the default theme (SCSS):

.bcp-popover {
    max-width: none;

    .bcp-row {
        display: flex;
    }

    .bcp-color {
        transition: all .1s ease-in-out;
        position: relative;
        width: 24px;
        height: 24px;
        border-radius: 50%;
        border: 1px solid #ddd;
        margin: 5px;
        cursor: pointer;

        &.bcp-light {
            color: #000;
        }

        &.bcp-dark {
            color: #fff;
        }

        &:hover,
        &.bcp-active {
            width: 30px;
            height: 30px;
            margin: 2px;
        }

        &.bcp-active {
            pointer-events: none;

            &:after {
                content: '\\2713';
                position: absolute;
                top: 50%;
                left: 50%;
                transform: translateX(-50%) translateY(-50%);
                font-size: 28px;
            }
        }
    }
}

Packages

Feel free to visit my other packages: