---
title: CustomField
description: CustomField
element: vaadin-custom-field
---

## Description

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

```html
<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
`has-tooltip`       | Set when the element has a slotted tooltip

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.

The following custom CSS properties are available for styling:

Custom CSS property                                |
:--------------------------------------------------|
| `--vaadin-input-field-error-color`               |
| `--vaadin-input-field-error-font-size`           |
| `--vaadin-input-field-error-font-weight`         |
| `--vaadin-input-field-error-line-height`         |
| `--vaadin-input-field-label-color`               |
| `--vaadin-input-field-label-font-size`           |
| `--vaadin-input-field-label-font-weight`         |
| `--vaadin-input-field-label-line-height`         |
| `--vaadin-input-field-helper-color`              |
| `--vaadin-input-field-helper-font-size`          |
| `--vaadin-input-field-helper-font-weight`        |
| `--vaadin-input-field-helper-line-height`        |
| `--vaadin-input-field-required-indicator-color`  |
| `--vaadin-input-field-required-indicator`        |

See [Styling Components](https://vaadin.com/docs/latest/styling/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:
```js
customField.formatValue = (fieldValues) => {
  return fieldValues.join("-");
}
```

See also: [CustomFieldFormatValueFn](#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:
```js
customField.parseValue = (componentValue) => {
  return componentValue.split("-");
}
```

See also: [CustomFieldParseValueFn](#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`](/elements/vaadin-custom-field#formatvalue)
and [`parseValue`](/elements/vaadin-custom-field#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](#customfieldchangeevent)

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

### invalid-changed

**Type:** [CustomFieldInvalidChangedEvent](#customfieldinvalidchangedevent)

Fired when the `invalid` property changes.

### validated

**Type:** [CustomFieldValidatedEvent](#customfieldvalidatedevent)

Fired whenever the field is validated.

### value-changed

**Type:** [CustomFieldValueChangedEvent](#customfieldvaluechangedevent)

Fired when the `value` property changes.

## Types

### CustomFieldChangeEvent

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

### CustomFieldFormatValueFn

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

### CustomFieldInvalidChangedEvent

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

### CustomFieldParseValueFn

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

### CustomFieldValidatedEvent

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

### CustomFieldValueChangedEvent

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