Getting Started with DateBox

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

DateBox is a widget that allows users to set a certain date, time, or date/time combination.

This tutorial shows how to configure basic DateBox features. The newly created widget allows users to set the date and time from a specific date range, logs this value to the console, and prevents users from specifying weekend days (Saturday and Sunday) and US bank holidays.

Refer to the subtopics for details on each configuration step. You can also see the full code below or download it from the following GitHub repository: getting-started-with-datebox:

jQuery
index.js
index.html
$(function() {
    const now = new Date();
    const holidays = [
        new Date(0, 0, 1),
        new Date(0, 0, 20),
        new Date(0, 1, 17),
        new Date(0, 4, 10),
        new Date(0, 4, 25),
        new Date(0, 5, 21),
        new Date(0, 6, 4),
        new Date(0, 8, 7),
        new Date(0, 9, 5),
        new Date(0, 9, 12),
        new Date(0, 10, 11),
        new Date(0, 10, 26),
        new Date(0, 10, 27),
        new Date(0, 11, 24),
        new Date(0, 11, 25),
        new Date(0, 11, 31)
    ];

    $("#dateBoxContainer").dxDateBox({
        type: "datetime",
        max: now,
        min: new Date(1900, 0, 1),
        value: now,
        onValueChanged: function(e) {
            console.log(e.value);
            console.log(e.previousValue);
        },
        disabledDates: function(args) {
            const dayOfWeek = args.date.getDay();
            const isWeekend = dayOfWeek === 0 || dayOfWeek === 6; 
            return args.view === "month" && (isWeekend || isHoliday(args.date)); 
        }
    });

    function isHoliday(date) {
        for (let holiday of holidays) {
            if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                return true;
            }          
        }
        return false;
    }
});
<!DOCTYPE html>
<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/20.1.4/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.1.4/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/20.1.4/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body class="dx-viewport">
        <div id="dateBox"></div>
    </body>
</html>
Angular
app.component.html
app.component.ts
app.service.ts
app.module.ts
<dx-date-box    
    type="datetime"
    [min]="minDate"
    [max]="now"
    [value]="now"
    (onValueChanged)="onValueChanged($event)"
    [disabledDates]="getDisabledDates">
</dx-date-box>
import { Component } from '@angular/core';
import { AppService  } from './app.service';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    title = 'Getting started with DateBox';
    holidays: Date[];
    now: Date = new Date();
    minDate: Date = new Date(1900, 0, 1);

    constructor(service: AppService) {
        this.holidays = service.getHolidays();
        this.getDisabledDates = this.getDisabledDates.bind(this);
    }

    onValueChanged(e) {
        console.log(e.previousValue);
        console.log(e.value);
    }

    getDisabledDates(args): boolean {
        const dayOfWeek = args.date.getDay();
        const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
        return args.view === "month" && (isWeekend || this.isHoliday(args.date));
    }

    isHoliday(date): boolean {
        for (let holiday of this.holidays) {
            if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                return true;
            }          
        }
        return false;
    }
}
import { Injectable } from '@angular/core';

const holidays = [
    new Date(0, 0, 1),
    new Date(0, 0, 20),
    new Date(0, 1, 17),
    new Date(0, 4, 10),
    new Date(0, 4, 25),
    new Date(0, 5, 21),
    new Date(0, 6, 4),
    new Date(0, 8, 7),
    new Date(0, 9, 5),
    new Date(0, 9, 12),
    new Date(0, 10, 11),
    new Date(0, 10, 26),
    new Date(0, 10, 27),
    new Date(0, 11, 24),
    new Date(0, 11, 25),
    new Date(0, 11, 31)
];

@Injectable()
export class AppService {

    getHolidays(): Date[] {
        return holidays;
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxDateBoxModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxDateBoxModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxDateBox
        type="datetime"
        :min="minDate"
        :max="now"
        :value="now"
        @value-changed="onValueChanged"
        :disabled-dates="getDisabledDates"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxDateBox } from 'devextreme-vue/date-box';

const holidays = [
    new Date(0, 0, 1),
    new Date(0, 0, 20),
    new Date(0, 1, 17),
    new Date(0, 4, 10),
    new Date(0, 4, 25),
    new Date(0, 5, 21),
    new Date(0, 6, 4),
    new Date(0, 8, 7),
    new Date(0, 9, 5),
    new Date(0, 9, 12),
    new Date(0, 10, 11),
    new Date(0, 10, 26),
    new Date(0, 10, 27),
    new Date(0, 11, 24),
    new Date(0, 11, 25),
    new Date(0, 11, 31)
]

export default {
    components: {
        DxDateBox
    },
    data() {
        return {
            now: Date(),
            minDate: new Date(1900, 0, 1)
        }
    },
    methods: {
        onValueChanged(e) {
            console.log(e.previousValue);
            console.log(e.value);
        },
        getDisabledDates(args) {
            const dayOfWeek = args.date.getDay();
            const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
            return args.view === "month" && (isWeekend || this.isHoliday(args.date));
        },
        isHoliday(date) {
            for (let holiday of holidays) {
                if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                    return true;
                }          
            }
            return false;
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

const holidays = [
    new Date(0, 0, 1),
    new Date(0, 0, 20),
    new Date(0, 1, 17),
    new Date(0, 4, 10),
    new Date(0, 4, 25),
    new Date(0, 5, 21),
    new Date(0, 6, 4),
    new Date(0, 8, 7),
    new Date(0, 9, 5),
    new Date(0, 9, 12),
    new Date(0, 10, 11),
    new Date(0, 10, 26),
    new Date(0, 10, 27),
    new Date(0, 11, 24),
    new Date(0, 11, 25),
    new Date(0, 11, 31)
]

class App extends React.Component {
    now = new Date();
    minDate = new Date(1900, 0, 1);

    constructor(props) {
        super(props);
        this.state = {
            dateBoxValue: this.now
        };
        this.getDisabledDates = this.getDisabledDates.bind(this);
        this.onValueChanged = this.onValueChanged.bind(this);
    }

    getDisabledDates(args) {
        const dayOfWeek = args.date.getDay();
        const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
        return args.view === "month" && (isWeekend || this.isHoliday(args.date));
    }

    isHoliday(date) {
        for (let holiday of holidays) {
            if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                return true;
            }          
        }
        return false;
    }

    onValueChanged(e) {
        console.log(e.previousValue);
        console.log(e.value);
        this.setState({
            dateBoxValue: e.value
        });
    } 

    render() {
        return (
            <DateBox      
                type="datetime"
                min={this.minDate}
                max={this.now}
                value={this.state.dateBoxValue}
                onValueChanged={this.onValueChanged}
                disabledDates={this.getDisabledDates}
            />
        );
    }
}
export default App;

Create the DateBox

Use the following code to create a basic DateBox:

jQuery
index.js
index.html
$(function() {
    $("#dateBox").dxDateBox({
        // Configuration goes here
     });
});
<!DOCTYPE html>
<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/20.1.4/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.1.4/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/20.1.4/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body class="dx-viewport">
        <div id="dateBox"></div>
    </body>
</html>
Angular
app.component.html
app.component.ts
app.module.ts
<dx-date-box
    <!-- Configuration goes here -->
>
</dx-date-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 { DxDateBoxModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxDateBoxModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxDateBox
        <!-- Configuration goes here -->
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxDateBox } from 'devextreme-vue/date-box';

export default {
    components: {
        DxDateBox
    }
}
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

class App extends React.Component {
    render() {
        return (
            <DateBox      
                // Configuration goes here
            />
        );
    }
}
export default App;

If you run this code, you will that see the DateBox that allows users to set the date only. Users will be allowed to set the time in the next step.

Set the DateBox Type

To allow users to specify the date and time, set the type to "datetime". This will implicitly set applyValueMode to "useButtons" (i.e., a user must press OK to submit their choices).

jQuery
index.js
$(function() {
    $("#dateBoxContainer").dxDateBox({
        type: "datetime"
    });
});
Angular
app.component.html
<dx-date-box    
    type="datetime">
</dx-date-box>
Vue
App.vue
<template>
    <DxDateBox
        type="datetime"
    />
</template>

<script>
    // ...
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

class App extends React.Component {
     render() {
        return (
            <DateBox      
                type="datetime"
            />
        );
    }
}
export default App;

Run this code and ensure it is possible to specify the date and time. In the next step, we will set an accepted date range.

Set the Accepted Date Range

To define the range from which users can select dates, specify the min and max options:

jQuery
index.js
$(function() {
    const now = new Date();

    $("#dateBoxContainer").dxDateBox({
        max: now,
        min: new Date(1900, 0, 1),
     });
});
Angular
app.component.html
app.component.ts
<dx-date-box ... 
    [min]="minDate"
    [max]="now">
</dx-date-box>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    minDate: Date = new Date(1900, 0, 1);
    now: Date = new Date();
}
Vue
App.vue
<template>
    <DxDateBox ...
        :min="minDate"
        :max="now"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxDateBox } from 'devextreme-vue/date-box';

export default {
    components: {
        DxDateBox
    },
    data() {
        return {
            minDate: new Date(1900, 0, 1)
            now: Date(),
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

class App extends React.Component {
    minDate = new Date(1900, 0, 1);
    now = new Date();

    render() {
        return (
            <DateBox      
                min={this.minDate}
                max={this.now}
            />
        );
    }
}
export default App;

Run the code and ensure that the only available dates are between 1 Jan 1900 and today. Next, we will set the widget's initial value.

Set the Value

To set the widget's value, specify the value option. In this tutorial, it is equal to the current date and time.

jQuery
index.js
$(function() {
    const now = new Date();

    $("#dateBoxContainer").dxDateBox({
        // ...
        value: now
    });
});
Angular
app.component.html
app.component.ts
<dx-date-box ...    
    [value]="now">
</dx-date-box>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    // ...
    now: Date = new Date();
}
Vue
App.vue
<template>
    <DxDateBox ...
        :value="now"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxDateBox } from 'devextreme-vue/date-box';

export default {
    components: {
        DxDateBox
    },
    data() {
        return {
            // ...
            now: Date(),
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

class App extends React.Component {
    // ...
    now = new Date();

    constructor(props) {
        super(props);
        this.state = {
            dateBoxValue: this.now
        };
    }

    render() {
        return (
            <DateBox ...
                value={this.state.dateBoxValue}
            />
        );
    }
}
export default App;

In the next step, we will handle the value change event.

Handle the Value Change Event

To handle value changes, implement the onValueChanged function. In this tutorial, it logs the previous and current values.

jQuery
index.js
$(function() {
    $("#dateBoxContainer").dxDateBox({
        // ...
        onValueChanged: function(e) {
            console.log(e.value);
            console.log(e.previousValue);
        },
    });
});
Angular
app.component.html
app.component.ts
<dx-date-box ...
    (onValueChanged)="onValueChanged($event)">
</dx-date-box>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    // ...
    onValueChanged(e) {
        console.log(e.previousValue);
        console.log(e.value);
    }
}
Vue
App.vue
<template>
    <DxDateBox ...
        @value-changed="onValueChanged"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxDateBox } from 'devextreme-vue/date-box';

export default {
    // ...
    methods: {
        onValueChanged(e) {
            console.log(e.previousValue);
            console.log(e.value);
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

class App extends React.Component {
    constructor(props) {
        // ...
        this.onValueChanged = this.onValueChanged.bind(this);
    }

    onValueChanged(e) {
        console.log(e.previousValue);
        console.log(e.value);
        this.setState({
            dateBoxValue: e.value
        });
    } 

    render() {
        return (
            <DateBox ...
                onValueChanged={this.onValueChanged}
            />
        );
    }
}
export default App;

In the next part, we will disable specific dates.

Disable Specific Dates

To prevent users from setting specific dates, use the disabledDates option. It can be set to a function or an array of Date values. In this tutorial, we implement a function that disables weekend days (Saturday and Sunday) and US bank holidays.

jQuery
index.js
$(function() {
    // ...
    const holidays = [
        new Date(0, 0, 1),
        new Date(0, 0, 20),
        new Date(0, 1, 17),
        new Date(0, 4, 10),
        new Date(0, 4, 25),
        new Date(0, 5, 21),
        new Date(0, 6, 4),
        new Date(0, 8, 7),
        new Date(0, 9, 5),
        new Date(0, 9, 12),
        new Date(0, 10, 11),
        new Date(0, 10, 26),
        new Date(0, 10, 27),
        new Date(0, 11, 24),
        new Date(0, 11, 25),
        new Date(0, 11, 31)
    ];

    $("#dateBoxContainer").dxDateBox({
        // ...
        disabledDates: function(args) {
            const dayOfWeek = args.date.getDay();
            const isWeekend = dayOfWeek === 0 || dayOfWeek === 6; 
            return args.view === "month" && (isWeekend || isHoliday(args.date)); 
        }
    });

    function isHoliday(date) {
        for (let holiday of holidays) {
            if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                return true;
            }          
        }
        return false;
    }
});
Angular
app.component.html
app.component.ts
app.service.ts
<dx-date-box ...
    [disabledDates]="getDisabledDates">
</dx-date-box>
import { Component } from '@angular/core';
import { AppService } from './app.service';

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

    constructor(service: AppService) {
        this.holidays = service.getHolidays();
        this.getDisabledDates = this.getDisabledDates.bind(this);
    }

    getDisabledDates(args): boolean {
        const dayOfWeek = args.date.getDay();
        const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
        return args.view === "month" && (isWeekend || this.isHoliday(args.date));
    }

    isHoliday(date): boolean {
        for (let holiday of this.holidays) {
            if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                return true;
            }          
        }
        return false;
    }
}
import { Injectable } from '@angular/core';

const holidays = [
    new Date(0, 0, 1),
    new Date(0, 0, 20),
    new Date(0, 1, 17),
    new Date(0, 4, 10),
    new Date(0, 4, 25),
    new Date(0, 5, 21),
    new Date(0, 6, 4),
    new Date(0, 8, 7),
    new Date(0, 9, 5),
    new Date(0, 9, 12),
    new Date(0, 10, 11),
    new Date(0, 10, 26),
    new Date(0, 10, 27),
    new Date(0, 11, 24),
    new Date(0, 11, 25),
    new Date(0, 11, 31)
];

@Injectable()
export class AppService {

    getHolidays(): Date[] {
        return holidays;
    }
}
Vue
App.vue
<template>
    <DxDateBox ...
        :disabled-dates="getDisabledDates"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxDateBox } from 'devextreme-vue/date-box';

const holidays = [
    new Date(0, 0, 1),
    new Date(0, 0, 20),
    new Date(0, 1, 17),
    new Date(0, 4, 10),
    new Date(0, 4, 25),
    new Date(0, 5, 21),
    new Date(0, 6, 4),
    new Date(0, 8, 7),
    new Date(0, 9, 5),
    new Date(0, 9, 12),
    new Date(0, 10, 11),
    new Date(0, 10, 26),
    new Date(0, 10, 27),
    new Date(0, 11, 24),
    new Date(0, 11, 25),
    new Date(0, 11, 31)
]

export default {
    // ...
    methods: {
        getDisabledDates(args) {
            const dayOfWeek = args.date.getDay();
            const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
            return args.view === "month" && (isWeekend || this.isHoliday(args.date));
        },
        isHoliday(date) {
            for (let holiday of holidays) {
                if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                    return true;
                }          
            }
            return false;
        }
    }
}
</script>
React
App.js
import React from 'react';

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

import { DateBox } from 'devextreme-react/date-box';

const holidays = [
    new Date(0, 0, 1),
    new Date(0, 0, 20),
    new Date(0, 1, 17),
    new Date(0, 4, 10),
    new Date(0, 4, 25),
    new Date(0, 5, 21),
    new Date(0, 6, 4),
    new Date(0, 8, 7),
    new Date(0, 9, 5),
    new Date(0, 9, 12),
    new Date(0, 10, 11),
    new Date(0, 10, 26),
    new Date(0, 10, 27),
    new Date(0, 11, 24),
    new Date(0, 11, 25),
    new Date(0, 11, 31)
];

class App extends React.Component {
    // ...

    constructor(props) {
        // ...
        this.getDisabledDates = this.getDisabledDates.bind(this);
    }

    getDisabledDates(args) {
        const dayOfWeek = args.date.getDay();
        const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
        return args.view === "month" && (isWeekend || this.isHoliday(args.date));
    }

    isHoliday(date) {
        for (let holiday of holidays) {
            if (date.getDate() === holiday.getDate() && date.getMonth() === holiday.getMonth()) {
                return true;
            }          
        }
        return false;
    }

    render() {
        return (
            <DateBox ...
                disabledDates={this.getDisabledDates}
            />
        );
    }
}
export default App;

Run the code and ensure that the disabled dates cannot be set.

You have now configured the basic DateBox features. For more details on this widget, explore the following resources: