diff --git a/articles/components/_input-field-common-features.adoc b/articles/components/_input-field-common-features.adoc index 1d04752574..a7bff483be 100644 --- a/articles/components/_input-field-common-features.adoc +++ b/articles/components/_input-field-common-features.adoc @@ -144,21 +144,24 @@ Disabled fields can be useful in situations where they can become enabled based //// -CONSTRAINT FEATURES +VALIDATION FEATURES //// -// tag::constraints-intro[] -[.collapsible-list] -== Constraints -// end::constraints-intro[] - +// tag::bad-input[] +[#bad-input] +.Bad Input +[%collapsible] +==== +Bad input refers to any input that cannot be parsed into a value of the field type. When an unparsable value is entered, the field resets the value to empty and becomes invalid. This constraint is non-configurable and enabled by default. +==== +// end::bad-input[] // tag::required[] [#required] .Required [%collapsible] ==== -Required fields are marked with an indicator next to the label, and become invalid if left empty after having been focused. An error message explaining that the field is required needs to be provided manually. +Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared. An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the `--lumo-required-field-indicator` style property. ==== @@ -192,11 +195,15 @@ The pattern is a regular expression used to validate the full value entered into .Allowed Characters [%collapsible] ==== -A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don't match the expression are rejected. +A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don't match the expression are rejected. Note, however, that programmatically set values are not subject to this restriction, even if they contain disallowed characters. ==== // end::allowed-chars[] - +// tag::binder[] +.Data Binding and Custom Validation +[NOTE] +Flow and Hilla offer an advanced API called Binder that allows you to bind data and add custom validation rules for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. +// end::binder[] //// diff --git a/articles/components/combo-box/index.adoc b/articles/components/combo-box/index.adoc index e8fb895663..28efb97b84 100644 --- a/articles/components/combo-box/index.adoc +++ b/articles/components/combo-box/index.adoc @@ -360,9 +360,14 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;allowed-chars] +Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by selecting an item from the overlay or through text input followed by kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=required;allowed-chars] [.example] -- @@ -388,6 +393,8 @@ include::{root}/frontend/demo/component/combobox/react/combo-box-validation.tsx[ endif::[] -- +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/date-picker/index.adoc b/articles/components/date-picker/index.adoc index 0c8179ef57..e59ab29f3d 100644 --- a/articles/components/date-picker/index.adoc +++ b/articles/components/date-picker/index.adoc @@ -48,18 +48,26 @@ endif::[] The date can be entered directly using the keyboard in the format of the current locale or through the date picker overlay. The overlay opens when the field is clicked or any input is entered when the field is focused. +[.collapsible-list] == Validation -To validate a date entered or selected, various ways may be used. For instance, you may want to allow only dates in a certain range, or you might not want to allow certain dates. Below are some of your options for date validation. +Date Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation typically occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. +Below is a list of supported constraints with more detailed information: -=== Min & Max Value +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== The valid input range of Date Picker can be restricted by defining `min` and `max` values. Dates before the `min` and after the `max` are disabled in the overlay. Helper text can be used to inform the user about the accepted range. +==== + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- - ifdef::lit[] [source,html] ---- @@ -82,10 +90,11 @@ include::{root}/frontend/demo/component/datepicker/react/date-picker-validation. endif::[] -- -ifdef::flow,lit[] +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + === Custom Validation -Date Picker supports custom validation, such as limiting the options to Monday through Friday. In the following example, select a date that's on a Sunday or a Saturday to see a custom validation message. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to limit the options to Monday through Friday. In the following example, try selecting a date that's on a Sunday or a Saturday to see a custom validation message. [.example] -- @@ -111,7 +120,9 @@ include::{root}/frontend/demo/component/datepicker/react/date-picker-custom-vali ---- endif::[] -- -endif::[] + +Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. + == Week Numbers diff --git a/articles/components/date-time-picker/index.adoc b/articles/components/date-time-picker/index.adoc index 8c626ebb47..0d574ec0a6 100644 --- a/articles/components/date-time-picker/index.adoc +++ b/articles/components/date-time-picker/index.adoc @@ -150,11 +150,23 @@ endif::[] -- +[.collapsible-list] == Validation -=== Min & Max Values +Date Time Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the date must meet to be considered valid. Validation typically occurs when the user initiates a date change, for example by selecting a date from the overlay or through text input followed by kbd:[Enter]. If the date is invalid, the field is visually highlighted in red, and an error message appears underneath the input. -You can define a `min` and `max` value for Date Time Picker if you need to restrict the input to a specific range: +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] + +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== +The valid input range of Date Time Picker can be restricted by defining `min` and `max` values. Dates and times before the `min` and after the `max` aren't available for selection in the overlay. Helper text can be used to inform the user about the accepted range. +==== + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -180,10 +192,11 @@ include::{root}/frontend/demo/component/datetimepicker/react/date-time-picker-va endif::[] -- -ifdef::flow,lit[] +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + === Custom Validation -If the `min` and `max` values aren't enough, you can also apply custom validation. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to restrict date selection to weekdays (Monday-Friday) and time selection to only certain hours. In the following example, try selecting a date that's on a weekend or a time that's outside opening hours to see a custom validation message. [.example] -- @@ -208,7 +221,9 @@ include::{root}/frontend/demo/component/datetimepicker/react/date-time-picker-cu ---- endif::[] -- -endif::[] + +Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. + == Week Numbers diff --git a/articles/components/email-field/index.adoc b/articles/components/email-field/index.adoc index 3b612aef79..69cec4d9e0 100644 --- a/articles/components/email-field/index.adoc +++ b/articles/components/email-field/index.adoc @@ -75,19 +75,26 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required] +Email Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=required] [#pattern] .Pattern [%collapsible] ==== -The pattern attribute is an additional validation criterion that you can set if, for example, a specific domain is required. The pattern is specified using a regular expression. +The pattern is a regular expression that specifies an email format. Any value that doesn't match the email format invalidates the field. By default, the https://tools.ietf.org/html/rfc5322#[RFC 5322] standard pattern is used. However, you can modify this pattern to add additional restrictions, for example, to require a specific domain. -The example below uses the pattern `.+@example\.com` and only accepts addresses in the `example.com` domain. +The example below uses a modified version of the RFC 5322 pattern and only accepts addresses in the `example.com` domain. ==== +The following example demonstrates how to specify these constraints and provide error messages: + [.example] -- ifdef::lit[] @@ -112,6 +119,10 @@ include::{root}/frontend/demo/component/emailfield/react/email-field-validation. endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/number-field/index.adoc b/articles/components/number-field/index.adoc index 2038316314..f6f67bd8e7 100644 --- a/articles/components/number-field/index.adoc +++ b/articles/components/number-field/index.adoc @@ -74,15 +74,34 @@ include::{root}/frontend/demo/component/numberfield/react/number-field-step-butt endif::[] -- -== Minimum and Maximum Value +[.collapsible-list] +== Validation -The valid input range of a Number Field is set by defining the minimum and maximum values. +Number Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. -You can set the helper text to give information about the range. +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] + +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== +The valid input range of a Number Field can be restricted by defining `min` and `max` values. Helper text can be used to inform the user about the accepted range. +==== + +.Step +[%collapsible] +==== +Refer to the <<#step,Step>> section for more details and an example. +==== + +include::{articles}/components/_input-field-common-features.adoc[tags=allowed-chars] + +The following example demonstrates how to create a quantity field using a combination of these constraints: [.example] -- - ifdef::lit[] [source,typescript] ---- @@ -105,6 +124,11 @@ include::{root}/frontend/demo/component/numberfield/react/number-field-validatio endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + + == Step The step value of a Number Field defines the numeric intervals that are allowed. diff --git a/articles/components/password-field/index.adoc b/articles/components/password-field/index.adoc index fb19d5c037..28837c0163 100644 --- a/articles/components/password-field/index.adoc +++ b/articles/components/password-field/index.adoc @@ -99,9 +99,14 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;min-and-max-length;allowed-chars] +Password Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=required;min-and-max-length;allowed-chars] [.example] -- @@ -127,6 +132,10 @@ include::{root}/frontend/demo/component/passwordfield/react/password-field-valid endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/text-area/index.adoc b/articles/components/text-area/index.adoc index cd6d8d2b42..a3d9133e1c 100644 --- a/articles/components/text-area/index.adoc +++ b/articles/components/text-area/index.adoc @@ -130,9 +130,14 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;pattern;min-and-max-length;allowed-chars] +Text Area provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars] [.example] -- @@ -158,6 +163,10 @@ include::{root}/frontend/demo/component/textarea/react/text-area-validation.tsx[ endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/text-field/index.adoc b/articles/components/text-field/index.adoc index 48152a4abe..d51bd7f090 100644 --- a/articles/components/text-field/index.adoc +++ b/articles/components/text-field/index.adoc @@ -71,9 +71,16 @@ endif::[] -- -// Constraints +[.collapsible-list] +== Validation -include::{articles}/components/_input-field-common-features.adoc[tags=constraints-intro;required;pattern;min-and-max-length;allowed-chars] +Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation typically occurs when the user initiates a value change, for example by entering input and pressing kbd:[Enter]. If the value is invalid, the field is visually highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=required;pattern;min-and-max-length;allowed-chars] + +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -99,6 +106,10 @@ include::{root}/frontend/demo/component/textfield/react/text-field-validation.ts endif::[] -- +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + +include::{articles}/components/_input-field-common-features.adoc[tags=binder] + // Readonly and disabled diff --git a/articles/components/time-picker/index.adoc b/articles/components/time-picker/index.adoc index ad0ec5f27b..510d09ff30 100644 --- a/articles/components/time-picker/index.adoc +++ b/articles/components/time-picker/index.adoc @@ -155,12 +155,23 @@ endif::[] -- - +[.collapsible-list] == Validation -=== Minimum & Maximum Value +Time Picker provides a validation mechanism based on constraints. Constraints allow you to define criteria that the time must meet to be considered valid. Validation typically occurs when the user initiates a time change, for example by selecting a time from the overlay or through text input followed by kbd:[Enter]. If the time is invalid, the field is visually highlighted in red, and an error message appears underneath the input. + +Below is a list of supported constraints with more detailed information: + +include::{articles}/components/_input-field-common-features.adoc[tags=bad-input;required] + +[#min-and-max-value] +.Min & Max Value +[%collapsible] +==== +The valid input range of Time Picker can be restricted by defining `min` and `max` values. Times before the `min` and after the `max` aren't displayed in the overlay. Helper text can be used to inform the user about the accepted range. +==== -You can define a minimum and maximum value for Time Picker if you need to restrict the input to a specific range: +The following example demonstrates how to specify these constraints and provide error messages: [.example] -- @@ -186,10 +197,11 @@ include::{root}/frontend/demo/component/timepicker/react/time-picker-validation. endif::[] -- -ifdef::flow,lit[] +It's important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback. + === Custom Validation -If the minimum and maximum values aren't sufficient for validation, you can also apply custom validation. +For more complex cases where constraint validation isn't enough, Flow and Hilla offer the Binder API that allows you to define custom validation rules. This is useful, for example, when you want to allow time selection only within separate intervals, like morning and afternoon slots. In the following example, try selecting a time that is between opening hours to see a custom validation message. [.example] -- @@ -214,7 +226,8 @@ include::{root}/frontend/demo/component/timepicker/react/time-picker-custom-vali ---- endif::[] -- -endif::[] + +Binder can also be used to organize data binding and validation for multiple fields, creating forms. You can learn more about Binder from the corresponding <<{articles}/flow/binding-data/components-binder-validation#,Flow>> and <<{articles}/hilla/lit/guides/forms/binder-validation#,Hilla>> articles. // Basic Features