Bootstrap Color Palette

GitHub license Maintenance GitHub release (latest by date) Packagist

BCP is a simple color palette for Bootstrap 4, like in Google doc, built on the top of Bootstrap 4 Popover plugin.


No color selected

Any contribution or feedback is highly welcomed, please feel free to create a pull request or submit a new issue.

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:

Option Default Description
colors There is no default value, so the plugin won't work unless you define one. The colors available in the plugin.
You can either import one of provided palettes, or define you own.
template
<div class="popover bcp-popover" role="tooltip">
    <div class="arrow"></div>
    <h3 class="popover-header"></h3>
    <div class="popover-body"></div>
</div>
The customized popover template.
If you need to change this option, make sure to keep the required bsd-popover class.
body
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;
}
A function used to generate the popover body.
It receive the palette colors as argument and returns a HTML string.

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"
        }
    ]
});

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:

Bootstrap 4 forms builder for Laravel 5.8+

This package uses in background Laravel Collective HTML to simplify Bootstrap 4 forms creation into Laravel applications.
Model form binding and automatic error display are supported, as well as most of Bootstrap forms features : form layouts, custom fields, input groups, ...

Github Documentation

PHP-CS-Fixer for Laravel 5.5+

This package allows to use PHP-CS-Fixer right into Laravel 5.5+ applications to format PHP code.

Github Documentation

Bootstrap 4 dialogs

BSD is a tiny and flexible collection of dialog popups based on Bootstrap 4 modals.
Custom dialogs can be easily defined, in addition to built-in ones (alert, confirm and prompt).

Github Documentation

Laravel Kvstore

A simple and easy to use key-value database store for Laravel 5.5+
All values are stored into database and managed using cache to avoid unecessary queries.
Casting is supported to manage values type.

Github Documentation

Php DotEnv

A simple and standalone DotEnv parser for PHP 5.6+

Github Documentation

Blade Indenter

A very simple formatter for Laravel 5.8+ Blade templates

Github Documentation