Getting Started with ColorBox
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:
$(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/23.1.5/css/dx.light.css">
<script type="text/javascript" src="https://cdn3.devexpress.com/jslib/23.1.5/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:
<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:
<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:
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"), hexadecimal with alpha values ("#FF0000FF"), 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
$(function() {
$("#color-box").dxColorBox({
value: "#000000",
editAlphaChannel: true
});
});Angular
<dx-color-box
value="#000000"
[editAlphaChannel]="true"
>
</dx-color-box>Vue
<template>
<DxColorBox
value="#000000"
:edit-alpha-channel="true"
/>
</template>
<script>
// ...
</script>React
// ...
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
$(function() {
$("#color-box").dxColorBox({
// ...
showClearButton: true,
applyButtonText: "Show notification",
label: "Pick a color"
});
});Angular
<dx-color-box ...
[showClearButton]="true"
applyButtonText="Show notification"
label="Pick a color"
>
</dx-color-box>Vue
<template>
<DxColorBox ...
:show-clear-button="true"
apply-button-text="Show notification"
label="Pick a color"
/>
</template>
<script>
// ...
</script>React
// ...
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
$(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
<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
<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
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;