Getting Started with ColorBox

NOTE
Before you start the tutorial, ensure DevExtreme is installed in your Angular, Vue, React, or jQuery application.

The ColorBox component allows users to enter a color or pick it from a drop-down editor.

This tutorial shows how to add a ColorBox component to a page and configure the component's core settings. As a result, you will create the following UI component:

Each section in this tutorial describes a single configuration step. You can also find the full source code in the following GitHub repository: getting-started-with-color-box.

Create a ColorBox

jQuery

Add DevExtreme to your jQuery application and use the following code to create a ColorBox component:

index.js
index.html
$(function() {
    $("#color-box").dxColorBox({ });
});
<html>
    <head>
        <!-- ... -->
        <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/22.1.6/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/22.1.6/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body>
        <div id="color-box"></div>
    </body>
</html>
Angular

Add DevExtreme to your Angular application and use the following code to create a ColorBox component:

app.component.html
app.component.ts
app.module.ts
<dx-color-box></dx-color-box>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {

}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxColorBoxModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxColorBoxModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue

Add DevExtreme to your Vue application and use the following code to create a ColorBox component:

App.vue
<template>
    <DxColorBox>
    </DxColorBox>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';
import { DxColorBox } from 'devextreme-vue/color-box';

export default {
    components: {
        DxColorBox
    }
}
</script>
React

Add DevExtreme to your React application and use the following code to create a ColorBox component:

App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import { ColorBox } from 'devextreme-react/color-box';

function App() {
    return (
        <ColorBox>
        </ColorBox>
    );
}

export default App;

Configure Values

The ColorBox accepts colors in hexadecimal ("#FF0000"), RGB ("rgb(255, 0, 0)"), and RGBA ("rgba(255, 0, 0, 1)") formats, as well as color names. When users select a color from the drop-down editor, the ColorBox displays the selected color as a string in hexadecimal format.

To allow users to control the transparency of the selected color, enable the editAlphaChannel property. If you enable this property, the component displays the selected color in RGBA format.

To specify the initially selected color, use the value property.

The following code specifies the initial color and enables transparency:

jQuery
index.js
$(function() {
    $("#color-box").dxColorBox({
        value: "#000000",
        editAlphaChannel: true
    });
});
Angular
app.component.html
<dx-color-box
    value="#000000"
    [editAlphaChannel]="true"
>
</dx-color-box>
Vue
App.vue
<template>
    <DxColorBox
        value="#000000"
        :edit-alpha-channel="true"
    />
</template>

<script>
// ...
</script>
React
App.js
// ...

function App() {
    // ...
    return (
        <ColorBox
            value="#000000"
            editAlphaChannel={true}
        />
    );
}

export default App;

Customize Buttons and Labels

Specify the following properties to add custom buttons to the input field, or configure the drop-down editor's buttons:

  • buttons
    Allows you to add custom buttons to the input text field.

  • showClearButton
    Specifies whether to display the Clear button in the ColorBox.

  • applyButtonText
    Specifies the caption of the button that applies changes and closes the drop-down editor.

  • cancelButtonText
    Specifies the caption of the button that cancels changes and closes the drop-down editor.

You can hide the editor's drop-down button to limit user input options to color code entry. To do this, disable the showDropDownButton property.

To add a label to the ColorBox, specify the label property. To change the label appearance, set the labelMode property to one of the following values:

  • "static" (default)
    The component displays the label above the input field.

  • "floating"
    The component uses the label as a placeholder, but the label moves to the position above the input field when the editor receives focus.

  • "hidden"
    The label is hidden.

The following code displays a Clear button, changes the Apply button's caption, and specifies a label for the ColorBox.

jQuery
index.js
$(function() {
    $("#color-box").dxColorBox({
        // ...
        showClearButton: true,
        applyButtonText: "Show notification",
        label: "Pick a color"
    });
});
Angular
app.component.html
<dx-color-box ...
    [showClearButton]="true"
    applyButtonText="Show notification"
    label="Pick a color"
>
</dx-color-box>
Vue
App.vue
<template>
    <DxColorBox ...
        :show-clear-button="true"
        apply-button-text="Show notification"
        label="Pick a color"
    />
</template>

<script>
// ...
</script>
React
App.js
// ...

function App() {
    // ...
    return (
        <ColorBox ...
            showClearButton={true}
            applyButtonText="Show notification"
            label="Pick a color"
        />
    );
}

export default App;

Handle Value Change

Users can change the value after they pick a shade or after they click the OK button. To switch between value change modes, use the applyValueMode property. Implement the onValueChanged function to handle value changes when users select a color in the drop-down editor or type a color code.

The following code displays a notification every time users change the ColorBox value. The selected color is applied to the notification's background.

jQuery
index.js
$(function() {
    $("#color-box").dxColorBox({
        // ...
        onValueChanged(e) {
            const toastColor = e.value;
            if (toastColor) {
                DevExpress.ui.notify({
                    message: "The color has been changed",
                    onShowing(e) {
                        $(e.component.content()).css("background-color", toastColor);
                    }
                });
            }
        }
    });
});
Angular
app.component.html
app.component.ts
<dx-color-box ...
    (onValueChanged)="onValueChanged($event)"
>
</dx-color-box>
import { Component } from '@angular/core';
import notify from 'devextreme/ui/notify';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    // ...
    toastColor: string;
    onValueChanged(e) {
        this.toastColor = e.value;
        if (this.toastColor) {
            notify({
                message: 'The color has been changed',
                onShowing: (e) => {
                    e.component.content().style.backgroundColor = this.toastColor;
                }
            });
        }
    }
}
Vue
App.vue
<template>
    <DxColorBox ...
        @value-changed="onValueChanged"
    />
</template>

<script>
// ...
import notify from "devextreme/ui/notify";

export default {
    components: {
        DxColorBox
    },
    data() {
        return {
            toastColor: ''
        };
    },
    methods: {
        onValueChanged(e) {
            this.toastColor = e.value;
            if (this.toastColor) {
                notify({
                    message: 'The color has been changed',
                    onShowing: (e) => {
                        e.component.content().style.backgroundColor = this.toastColor;
                    }
                });
            }
        }
    }
}
</script>
React
App.js
import React, { useCallback } from "react";
import "devextreme/dist/css/dx.light.css";

import { ColorBox } from 'devextreme-react/color-box';
import notify from "devextreme/ui/notify";

function App() {
    const onValueChanged = useCallback((e) => {
        const toastColor = e.value;
        if (toastColor) {
            notify({
                message: 'The color has been changed',
                onShowing: (e) => {
                    e.component.content().style.backgroundColor = toastColor;
                }
            });
        }
    }, []);

    return (
        <ColorBox ...
            onValueChanged={onValueChanged}
        />
    );
}

export default App;