CustomField

Description #

<vaadin-custom-field> is a web component for wrapping multiple components as a single field.

<vaadin-custom-field label="Appointment time">
  <vaadin-date-picker></vaadin-date-picker>
  <vaadin-time-picker></vaadin-time-picker>
</vaadin-custom-field>

Styling #

The following shadow DOM parts are available for styling:

Part name	Description
label	The slotted label element wrapper
helper-text	The slotted helper text element wrapper
error-message	The slotted error message element wrapper
required-indicator	The required state indicator element
input-fields	The slotted input elements wrapper

The following state attributes are available for styling:

Attribute	Description
invalid	Set when the element is invalid
focused	Set when the element is focused
has-label	Set when the element has a label
has-value	Set when the element has a value
has-helper	Set when the element has helper text
has-error-message	Set when the element has an error message

You may also manually set disabled or readonly attribute on this component to make the label part look visually the same as on a <vaadin-text-field> when it is disabled or readonly.

See Styling Components documentation.

Properties #

accessibleName #

Type: string | null | undefined

String used to label the component to screen reader users.

accessibleNameRef #

Type: string | null | undefined

Id of the element used as label of the component to screen reader users.

errorMessage #

Type: string | null | undefined

Error to show when the field is invalid.

formatValue #

Type: CustomFieldFormatValueFn | undefined

A function to format the values of the individual fields contained by the custom field into a single component value. The function receives an array of all values of the individual fields in the order of their presence in the DOM, and must return a single component value. This function is called each time a value of an internal field is changed.

Example:

customField.formatValue = (fieldValues) => {
  return fieldValues.join("-");
}

See also: CustomFieldFormatValueFn

helperText #

Type: string | null | undefined

String used for the helper text.

inputs #

Type: HTMLElement[] | undefined

Array of available input nodes

invalid #

Type: boolean

Set to true when the field is invalid.

label #

Type: string | null | undefined

The label text for the input node. When no light dom defined via [slot=label], this value will be used.

manualValidation #

Type: boolean

Set to true to enable manual validation mode. This mode disables automatic constraint validation, allowing you to control the validation process yourself. You can still trigger constraint validation manually with the validate() method or use checkValidity() to assess the component's validity without affecting the invalid state. In manual validation mode, you can also manipulate the invalid property directly through your application logic without conflicts with the component's internal validation.

name #

Type: string | null | undefined

The name of the control, which is submitted with the form data.

parseValue #

Type: CustomFieldParseValueFn | undefined

A function to parse the component value into values for the individual fields contained by the custom field. The function receives the component value, and must return an array of values for the individual fields in the order of their presence in the DOM. The function is called each time the value of the component changes.

Example:

customField.parseValue = (componentValue) => {
  return componentValue.split("-");
}

See also: CustomFieldParseValueFn

required #

Type: boolean

Specifies that the user must fill in a value.

value #

Type: string | null | undefined

The value of the field. When wrapping several inputs, it will contain \t (Tab character) as a delimiter indicating parts intended to be used as the corresponding inputs values. Use the formatValue and parseValue properties to customize this behavior.

Methods #

checkValidity #

Type: () => boolean

Returns true if the current inputs values satisfy all constraints (if any).

validate #

Type: () => boolean

Validates the field and sets the invalid property based on the result.

The method fires a validated event with the result of the validation.

Events #

change #

Type: CustomFieldChangeEvent

Fired when the user commits a value change for any of the internal inputs.

invalid-changed #

Type: CustomFieldInvalidChangedEvent

Fired when the invalid property changes.

validated #

Type: CustomFieldValidatedEvent

Fired whenever the field is validated.

value-changed #

Type: CustomFieldValueChangedEvent

Fired when the value property changes.

Types #

CustomFieldChangeEvent #

/**
 * Fired when the user commits a value change.
 */
export type CustomFieldChangeEvent = Event & {
  target: CustomField;
};

CustomFieldFormatValueFn #

export type CustomFieldFormatValueFn = (inputValues: unknown[]) => string;

CustomFieldInvalidChangedEvent #

/**
 * Fired when the `invalid` property changes.
 */
export type CustomFieldInvalidChangedEvent = CustomEvent<{ value: boolean }>;

CustomFieldParseValueFn #

export type CustomFieldParseValueFn = (value: string) => unknown[];

CustomFieldValidatedEvent #

/**
 * Fired whenever the field is validated.
 */
export type CustomFieldValidatedEvent = CustomEvent<{ valid: boolean }>;

CustomFieldValueChangedEvent #

/**
 * Fired when the `value` property changes.
 */
export type CustomFieldValueChangedEvent = CustomEvent<{ value: string }>;