JavaScript/jQuery Validator - CustomRule

A rule with custom validation logic.

import { CustomRule } from "devextreme/common"

Type:

To specify the custom rule, set the type to "custom" and declare the validationCallback function.

You can also set a custom message, specify whether empty values are valid, and whether the rule should be re-evaluated, even if the target value is the same.

ignoreEmptyValue

If true, the validationCallback is not executed for null, undefined, false, and empty strings.

Type:

Boolean

Default Value: false

message

Specifies the message that is shown if the rule is broken.

Type:

String

Default Value: 'Value is invalid'

An error message can be specified as follows:

Hard-code the message

jQuery

index.js

$(function() {
    $("#textBox").dxTextBox({ ... })
        .dxValidator({
            type: "custom",
            message: "My custom message"
        });
});

Angular

app.component.html

app.module.ts

<dx-text-box> 
    <dx-validator>
        <dxi-validation-rule 
            type="custom" 
            message="My custom message">
        </dxi-validation-rule>
    </dx-validator>
</dx-text-box>

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

import { DxValidatorModule,
         DxTextBoxModule } from 'devextreme-angular';

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

Vue

App.vue

<template>
    <DxTextBox>
        <DxValidator>
            <DxCustomRule
                message="My custom message"
            />
        </DxValidator>
    </DxTextBox>
</template>

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

import { DxTextBox } from 'devextreme-vue/text-box';
import {
    DxValidator,
    DxCustomRule
} from 'devextreme-vue/validator';

export default {
    components: {
        DxTextBox,
        DxValidator,
        DxCustomRule
    }
}
</script>

React

App.js

import React from 'react';

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

import { TextBox } from 'devextreme-react/text-box';
import {
    Validator,
    CustomRule
} from 'devextreme-react/validator';

class App extends React.Component {
    render() {
        return (
            <TextBox>
                <Validator>
                    <CustomRule
                        message="My custom message" />
                </Validator>
            </TextBox>
        );
    }
}
export default App;

Hide the message

jQuery

index.js

$(function() {
    $("#textBox").dxTextBox({ ... })
        .dxValidator({
            type: "custom",
            message: ""
        });
});

Angular

app.component.html

app.module.ts

<dx-text-box>
    <dx-validator>
        <dxi-validation-rule 
            type="custom" 
            message="">
        </dxi-validation-rule>
    </dx-validator>
</dx-text-box>

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

 import { DxValidatorModule,
          DxTextBoxModule } from 'devextreme-angular';

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

Vue

App.vue

<template>
    <DxTextBox>
        <DxValidator>
            <DxCustomRule
                message=""
            />
        </DxValidator>
    </DxTextBox>
</template>

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

import { DxTextBox } from 'devextreme-vue/text-box';
import {
    DxValidator,
    DxCustomRule
} from 'devextreme-vue/validator';

export default {
    components: {
        DxTextBox,
        DxValidator,
        DxCustomRule
    }
}
</script>

React

App.js

import React from 'react';

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

import { TextBox } from 'devextreme-react/text-box';
import {
    Validator,
    CustomRule
} from 'devextreme-react/validator';

class App extends React.Component {
    render() {
        return (
            <TextBox>
                <Validator>
                    <CustomRule
                        message="" />
                </Validator>
            </TextBox>
        );
    }
}
export default App;

Display the editor's name in the message

jQuery

index.js

$(function() {
    $("#textBox").dxTextBox({ ... })
        .dxValidator({
            name: "Password", // The error message will be "Password is invalid"
            validationRules: [{
                type: "custom"
            }]
        });
});

Angular

app.component.html

app.module.ts

<dx-text-box>
    <!-- The error message will be "Password is invalid" -->
    <dx-validator name="Password">
        <dxi-validation-rule 
            type="custom">
        </dxi-validation-rule>
    </dx-validator>
</dx-text-box>

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

import { DxValidatorModule,
         DxTextBoxModule } from 'devextreme-angular';

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

Vue

App.vue

<template>
    <DxTextBox>
        <!-- The error message will be "Password is invalid" -->
        <DxValidator name="Password">
            <DxCustomRule />
        </DxValidator>
    </DxTextBox>
</template>

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

import { DxTextBox } from 'devextreme-vue/text-box';
import {
    DxValidator,
    DxCustomRule
} from 'devextreme-vue/validator';

export default {
    components: {
        DxValidator,
        DxCustomRule
    }
}
</script>

React

App.js

import React from 'react';

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

import { TextBox } from 'devextreme-react/text-box';
import {
    Validator,
    CustomRule
} from 'devextreme-react/validator';

class App extends React.Component {
    render() {
        return (
            <TextBox>
                {/* The error message will be "Password is invalid" */}
                <Validator name="Password">
                    <CustomRule />
                </Validator>
            </TextBox>
        );
    }
}

export default App;

reevaluate

Indicates whether the rule should be always checked for the target value or only when the target value changes.

Type:

Boolean

Default Value: false

If you set this property to false, the rule is checked only when you change an editor's value. If you enter a value and validate the editor's value twice, the validation callback is executed only once.

If you set this property to true, the rule is checked every time an editor is validated. If you enter a value and validate the editor's value twice, the validation callback is executed twice.

type

Specifies the rule type. Set it to "custom" to use the CustomRule.

Type:

ValidationRuleType

validationCallback

A function that validates the target value.

Type:

Function

Function parameters:

options:

Object

An object that defines validation parameters.

Object structure:

Name	Type	Description
column	Object	The column which the cell being validated belongs to. Exists only when you validate a built-in editor in DataGrid or TreeList.
data	Object	Current row data. Exists only when you validate DataGrid or TreeList cell values.
formItem	Object	The form item being validated. Exists only when you validate a built-in editor in the Form UI component.
rule	Object	The rule being checked.
validator	Object	The Validator object that initiated the validation.
value	String \| Number	The validated value.

Return Value:

Boolean

true if the value is valid; otherwise, false.

The following code sample shows a validationCallback example. The validateNumber function accepts a number and returns true if the number is even and false if it is odd:

jQuery

index.js

$(function () {
    $("#numberBoxContainer").dxNumberBox({
        value: 4
    }).dxValidator({
        validationRules: [{
            type: "custom",
            validationCallback: validateNumber,
            message: "An even number is expected"
        }]
    });
});
function validateNumber (e) {
    return e.value % 2 == 0;
}

Angular

app.component.html

app.component.ts

<dx-number-box [value]="4">
    <dx-validator>
        <dxi-validation-rule type="custom" 
            [validationCallback]="validateNumber" 
            message="An even number is expected">
        </dxi-validation-rule>
    </dx-validator>
</dx-number-box>

import { DxNumberBoxModule, DxValidatorModule } from "devextreme-angular";
import { ValidationCallbackData } from 'devextreme-angular/common';
// ...
export class AppComponent {
    validateNumber(e: ValidationCallbackData) {
        return e.value % 2 == 0;
    }
}
@NgModule({
    imports: [
        DxNumberBoxModule,
        DxValidatorModule,
        // ...
    ],
    // ...
})

Vue

App.vue

<template>
    <DxNumberBox :value="4">
        <DxValidator>
            <DxCustomRule
                :validation-callback="validateNumber"
                message="An even number is expected"
            />
        </DxValidator>
    </DxNumberBox>
</template>

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

import DxNumberBox from 'devextreme-vue/number-box';
import DxValidator, {
    DxCustomRule
} from 'devextreme-vue/validator';

export default {
    components: {
        DxNumberBox,
        DxValidator,
        DxCustomRule
    },
    methods: {
        validateNumber(e) {
            return e.value % 2 == 0;
        }
    }
}
</script>

React

App.js

import React from 'react';

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

import NumberBox from 'devextreme-react/number-box';
import Validator, {
    CustomRule
} from 'devextreme-react/validator';

class App extends React.Component {
    validateNumber(e) {
        return e.value % 2 == 0;
    }

    render() {
        return (
            <NumberBox defaultValue={4}>
                <Validator>
                    <CustomRule
                        validationCallback={validateNumber}
                        message="An even number is expected"
                    />
                </Validator>
            </NumberBox>
        );
    }
}
export default App;

The code snippet below demonstrates how to implement multiple validation messages in one CustomRule:

jQuery

index.js

$(function () {
    $("#numberBoxContainer").dxNumberBox({}).dxValidator({
        validationRules: [{
            type: "custom",
            validationCallback: validateNumber,
        }]
    });
});
function validateNumber (e) {
    switch (true) {
        case (e.value < 0):
            e.rule.message = "Enter a number greater than 0";
            return false;
        case (e.value > 100):
            e.rule.message = "Enter a number less than 100";
            return false;
        case (e.value % 2 !=0):
            e.rule.message = "Enter an even number";
            return false;
        default:
            return true;
    }
}

Angular

app.component.html

app.component.ts

<dx-number-box>
    <dx-validator>
        <dxi-validation-rule
            type="custom" 
            [validationCallback]="validateNumber" 
        >
        </dxi-validation-rule>
    </dx-validator>
</dx-number-box>

import { DxNumberBoxModule, DxValidatorModule } from "devextreme-angular";
import { ValidationCallbackData } from 'devextreme-angular/common';
// ...
export class AppComponent {
    validateNumber(e: ValidationCallbackData) {
        switch (true) {
            case (e.value < 0):
                e.rule.message = "Enter a number greater than 0";
                return false;
            case (e.value > 100):
                e.rule.message = "Enter a number less than 100";
                return false;
            case (e.value % 2 !=0):
                e.rule.message = "Enter an even number";
                return false;
            default:
                return true;
        }
    }
}
@NgModule({
    imports: [
        DxNumberBoxModule,
        DxValidatorModule,
        // ...
    ],
    // ...
})

Vue

App.vue

<template>
    <DxNumberBox>
        <DxValidator>
            <DxCustomRule
                :validation-callback="validateNumber"
            />
        </DxValidator>
    </DxNumberBox>
</template>

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

import DxNumberBox from 'devextreme-vue/number-box';
import DxValidator, {
    DxCustomRule
} from 'devextreme-vue/validator';

export default {
    components: {
        DxNumberBox,
        DxValidator,
        DxCustomRule
    },
    methods: {
        validateNumber(e) {
            switch (true) {
                case (e.value < 0):
                    e.rule.message = "Enter a number greater than 0";
                    return false;
                case (e.value > 100):
                    e.rule.message = "Enter a number less than 100";
                    return false;
                case (e.value % 2 !=0):
                    e.rule.message = "Enter an even number";
                    return false;
                default:
                    return true;
            }
        }
    }
}
</script>

React

App.js

import React from 'react';

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

import NumberBox from 'devextreme-react/number-box';
import Validator, {
    CustomRule
} from 'devextreme-react/validator';

class App extends React.Component {
    function validateNumber(e) {
        switch (true) {
            case (e.value < 0):
                e.rule.message = "Enter a number greater than 0";
                return false;
            case (e.value > 100):
                e.rule.message = "Enter a number less than 100";
                return false;
            case (e.value % 2 !=0):
                e.rule.message = "Enter an even number";
                return false;
            default:
                return true;
        }
    }

    render() {
        return (
            <NumberBox>
                <Validator>
                    <CustomRule
                        validationCallback={validateNumber}
                    />
                </Validator>
            </NumberBox>
        );
    }
}
export default App;

JavaScript/jQuery Validator - CustomRule

See Also

ignoreEmptyValue

message

jQuery

Angular

Vue

React

jQuery

Angular

Vue

React

jQuery

Angular

Vue

React

reevaluate

type

validationCallback

jQuery

Angular

Vue

React

jQuery

Angular

Vue

React