JavaScript/jQuery Validator - CustomRule

A rule with custom validation logic.

import { CustomRule } from "devextreme/common"
Type:

Object

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.

See Also

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'

You can configure an error message in the following ways:

  • Specify a hard-coded message:

    jQuery
    index.js
    $("#textBox").dxTextBox({
    // ...
}).dxValidator({
    type: "custom",
    message: "My custom message"
});
    Angular
    app.component.html
    app.module.ts
    <dx-text-box>
    <dx-validator>
        <dxi-validator-validation-rule
            type="custom"
            message="My custom message">
        </dxi-validator-validation-rule>
    </dx-validator>
</dx-text-box>
    import { DxValidatorModule, DxTextBoxModule } from 'devextreme-angular';
// ...

@NgModule({
    imports: [
        DxTextBoxModule,
        DxValidatorModule,
    ],
})
    Vue
    App.vue
    <template>
    <DxTextBox>
        <DxValidator>
            <DxCustomRule
                message="My custom message"
            />
        </DxValidator>
    </DxTextBox>
</template>

<script setup lang="ts">
import { DxTextBox } from 'devextreme-vue/text-box';
import { DxValidator, DxCustomRule } from 'devextreme-vue/validator';

</script>
    React
    App.tsx
    import { TextBox } from 'devextreme-react/text-box';
import { Validator, CustomRule } from 'devextreme-react/validator';

function App() {
    return (
        <TextBox>
            <Validator>
                <CustomRule
                    message="My custom message"
                />
            </Validator>
        </TextBox>
    );
}

  • Hide the message:

    jQuery
    index.js
    $("#textBox").dxTextBox({
    // ...
}).dxValidator({
    type: "custom",
    message: ""
});
    Angular
    app.component.html
    <dx-text-box>
    <dx-validator>
        <dxi-validator-validation-rule
            type="custom"
            message="">
        </dxi-validator-validation-rule>
    </dx-validator>
</dx-text-box>
    Vue
    App.vue
    <template>
    <DxTextBox>
        <DxValidator>
            <DxCustomRule
                message=""
            />
        </DxValidator>
    </DxTextBox>
</template>
    React
    App.tsx
    import { TextBox } from 'devextreme-react/text-box';
import { Validator, CustomRule } from 'devextreme-react/validator';

function App() {
    return (
        <TextBox>
            <Validator>
                <CustomRule
                    message=""
                />
            </Validator>
        </TextBox>
    );
}

  • Display the editor's name in the default message (for instance, "Password is invalid"):

    jQuery
    index.js
    $("#textBox").dxTextBox({
    // ...
}).dxValidator({
    name: "Password",
    validationRules: [{
        type: "custom",
    }],
});
    Angular
    app.component.html
    <dx-text-box>
    <dx-validator name="Password">
        <dxi-validator-validation-rule
            type="custom"
        ></dxi-validator-validation-rule>
    </dx-validator>
</dx-text-box>
    Vue
    App.vue
    <template>
    <DxTextBox>
        <DxValidator name="Password">
            <DxCustomRule />
        </DxValidator>
    </DxTextBox>
</template>
    React
    App.tsx
    import { TextBox } from 'devextreme-react/text-box';
import { Validator, CustomRule } from 'devextreme-react/validator';

function App() {
    return (
        <TextBox>
            <Validator name="Password">
                <CustomRule />
            </Validator>
        </TextBox>
    );
}

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 to which the cell being validated belongs. 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 any

The validated value. Note that the value type depends on the validated editor.
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-validator-validation-rule type="custom" 
            [validationCallback]="validateNumber" 
            message="An even number is expected">
        </dxi-validator-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.fluent.blue.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.fluent.blue.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-validator-validation-rule
            type="custom" 
            [validationCallback]="validateNumber" 
        >
        </dxi-validator-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.fluent.blue.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.fluent.blue.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;