InputField

A configurable InputField component used to gather user input through a text field.

Import

React

// with @dhl-official/react-library:
import { DhlInputField } from "@dhl-official/react-library"

// with @dhl-official/ui-libraries/react-library:
import { DhlInputField } from "@dhl-official/ui-libraries/react-library"

Angular

If the DUIL has been installed, you can use the web component directly:

<dhl-input-field></dhl-input-field>

Vue.js

// with @dhl-official/vue-library:
import { DhlInputField } from "@dhl-official/vue-library"

// with @dhl-official/ui-libraries/vue-library:
import { DhlInputField } from "@dhl-official/ui-libraries/vue-library"

Code

React

<DhlInputField
  variant={{
    label: 'Label',
    placeholder: 'Placeholder',
  }}
></DhlInputField>

Angular

<dhl-input-field
  [variant]="{
    label: 'Label',
    placeholder: 'Placeholder',
  }"
></dhl-input-field>

Vue.js

<dhl-input-field
  :variant.prop="{
    label: 'Label',
    placeholder: 'Placeholder',
  }"
></dhl-input-field>

Interactive Demo

Examples with prefix / suffix addon

Example 1

Addon type: "prefix"

Code example

<DhlInputField
  variant={{
    label: "Label",
    placeholder: "Placeholder",
  }}
  addon={{
    type: "prefix",
    label: "Unit"
  }}
/>

Example 2

Addon type: "suffix" with options, colorVariant: "gray", validation type: "valid"

Code example

<DhlInputField
  variant={{
    label: "Label",
    placeholder: "Placeholder",
  }}
  addon={{
    type: "suffix",
    label: "Unit",
    colorVariant: ColorVariants.gray  
  }}
  validation={{
    type: "valid",
    message: "Validation message"
  }}
/>

Example 3

Addon type: "prefix" with options

Code example

<DhlInputField
  variant={{
    label: "Label",
    placeholder: "Placeholder",
  }}
  addon={{
    type: "prefix",
    label: "Unit",
    colorVariant: ColorVariants.white,
    options: [
      {
        label: "g",
        value: "g"
      },
      {
        label: "kg",
        value: "kg"
      },
      {
        label: "oz",
        value: "oz"
      },
      {
        label: "lb",
        value: "lb"
      },
    ],  
  }}
/>

Example 4

Addon type: "suffix" with options, colorVariant: "gray", validation type: "invalid"

Code example

<DhlInputField
  variant={{
    label: "Label",
    placeholder: "Placeholder",
  }}
  addon={{
    type: "suffix",
    label: "Unit",
    colorVariant: ColorVariants.gray,
    options: [
      {
        label: "g",
        value: "g"
      },
      {
        label: "kg",
        value: "kg"
      },
      {
        label: "oz",
        value: "oz"
      },
      {
        label: "lb",
        value: "lb"
      },
    ],
  }}
  validation={{
    type: "invalid",
    message: "Validation message"
  }}
/>

Examples with Number Input Validation

info

The maxDigits and decimalPoint props only work when type="number". These props are designed specifically for numeric input validation and will have no effect on other input types.

Example: Limiting Integer Digits

Using maxDigits to limit the number of digits before the decimal point (e.g., max 5 digits):

Code example

<DhlInputField
  type="number"
  maxDigits={5}
  variant={{
    label: "Amount (Max 5 digits)",
    placeholder: "Enter amount",
  }}
/>

Example: Limiting Decimal Places

Using decimalPoint to limit decimal places (e.g., 2 decimal places for currency):

Code example

<DhlInputField
  type="number"
  decimalPoint={2}
  variant={{
    label: "Price (2 decimals)",
    placeholder: "Enter price",
  }}
/>

Example: Combining Both Validations

Combining maxDigits and decimalPoint for precise control (e.g., max 6 digits, 2 decimals):

Code example

<DhlInputField
  type="number"
  maxDigits={6}
  decimalPoint={2}
  variant={{
    label: "Price (Max 6 digits, 2 decimals)",
    placeholder: "Enter price",
  }}
/>

Example: Block Decimals Entirely

Using decimalPoint={0} to prevent decimal input (integers only):

Code example

<DhlInputField
  type="number"
  decimalPoint={0}
  variant={{
    label: "Quantity (Integers only)",
    placeholder: "Enter quantity",
  }}
/>

Decimal Separator Configuration

When using type="number" with decimal values, you can configure the decimal separator using the decimalSeparator prop. This is useful for accommodating different locale preferences (e.g., European format uses comma, US format uses dot).

European Format (Comma Separator)

Code example

<DhlInputField
  type="number"
  decimalPoint={2}
  decimalSeparator=","
  variant={{
    label: "Price (EUR)",
    placeholder: "e.g., 123,45",
  }}
/>

US Format (Dot Separator)

Code example

<DhlInputField
  type="number"
  decimalPoint={2}
  decimalSeparator="."
  variant={{
    label: "Price (USD)",
    placeholder: "e.g., 123.45",
  }}
/>

Key Features:

• When decimalSeparator is set, the input automatically uses type="text" internally to avoid browser validation issues
• Users can type either comma or dot, and the value is automatically normalized to the configured separator
• The normalized value is what gets submitted with the form
• Works together with decimalPoint and maxDigits props to limit decimal places and integer digits

Readme

Usage

Dhl-input-field

Snippets of code in HTML and JavaScript to show some of the use cases for the component. The code is not meant to be executed, but to be used as a reference for the usage of the component.
Angular, React and Vue usages are not included in this documentation, but can be easily derived from the html and javascript code.

default usage

variant.label is required. variant.placeholder is optional. variant.type was removed because animated behavior of label and placeholder is no longer supported. When placeholder is not provided, then label stays permanently animated.

<form novalidate>
  <dhl-input-field name="dhl-input-field-custom-element"></dhl-input-field>
  <dhl-button
    type="reset"
    variant="outline"
    >reset</dhl-button
  >
  <dhl-button type="submit">submit</dhl-button>
</form>

<script type="module">
  const form = document.querySelector("form");
  const input = document.querySelector("dhl-input-field");

  input.variant = {
    label: "Label",
    placeholder: "Placeholder",
  };

  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    console.log(Object.fromEntries(new FormData(form)));
    return await form.checkValidity();
  });
</script>

usage with validation (required) and (browser) default validation message

<form novalidate>
  <dhl-input-field
    name="dhl-input-field-custom-element"
    required
  >
  </dhl-input-field>
  <dhl-button
    type="reset"
    variant="outline"
    >reset</dhl-button
  >
  <dhl-button type="submit">submit</dhl-button>
</form>

<script type="module">
  const form = document.querySelector("form");
  const input = document.querySelector("dhl-input-field");

  input.variant = {
    label: "Label",
    placeholder: "Placeholder",
  };

  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    console.log(Object.fromEntries(new FormData(form)));
    return await form.checkValidity();
  });
</script>

usage with validation (required) and custom validation message

<form novalidate>
  <dhl-input-field
    name="dhl-input-field-custom-element"
    required
  >
  </dhl-input-field>
  <dhl-button
    type="reset"
    variant="outline"
    >reset</dhl-button
  >
  <dhl-button type="submit">submit</dhl-button>
</form>

<script type="module">
  const form = document.querySelector("form");
  const input = document.querySelector("dhl-input-field");

  input.variant = {
    label: "Label",
    placeholder: "Placeholder",
  };

  const validationMessageInvalid = "This field is invalid";
  const validationMessageValid = "This field valid";

  form.addEventListener("submit", async (e) => {
    const isValid = await e.target.checkValidity();
    if (isValid) {
      input.validation = {
        type: "valid",
        message: validationMessageValid,
      };
    } else {
      input.validation = {
        type: "invalid",
        message: validationMessageInvalid,
      };
    }
    return isValid;
  });
</script>

usage with tooltip

The tooltip prop attaches a popover to the right icon. On mobile viewports (< 768 px) set isMobileVariant: true to anchor the tooltip below the input so it does not obscure the label or keyboard. The component automatically flips the tooltip back above the input when there is insufficient space below.

<dhl-input-field id="input-tooltip"></dhl-input-field>

<script type="module">
  const input = document.querySelector("#input-tooltip");

  input.variant = { label: "Shipment weight (kg)" };
  input.rightIcon = "path/to/info-icon.svg";
  input.tooltip = {
    title: "Weight guidelines",
    description: "Maximum weight per parcel is 31.5 kg for standard domestic shipments.",
    placement: "top",
    isMobileVariant: true,
  };
</script>

usage with custom events

<form novalidate>
  <dhl-input-field
    name="dhl-input-field-custom-element"
    required
  >
  </dhl-input-field>
  <dhl-button
    type="reset"
    variant="outline"
    >reset</dhl-button
  >
  <dhl-button type="submit">submit</dhl-button>
  <dhl-text></dhl-text>
</form>

<script type="module">
  const form = document.querySelector("form");
  const input = document.querySelector("dhl-input-field");
  const text = document.querySelector("dhl-text");

  input.variant = {
    label: "Label",
    placeholder: "Placeholder",
  };

  const validationMessageInvalid = "This field is invalid";
  const validationMessageValid = "This field valid";

  input.addEventListener("dhlBlur", async (e) => {
    const isValid = await e.target.checkValidity();
    if (isValid) {
      input.validation = {
        type: "valid",
        message: validationMessageValid,
      };
    } else {
      input.validation = {
        type: "invalid",
        message: validationMessageInvalid,
      };
    }
  });

  input.addEventListener("dhlChange", async (e) => {
    text.innerHTML = e.target.value;
  });

  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    console.log(Object.fromEntries(new FormData(form)));
    return await form.checkValidity();
  });
</script>

Properties

Property	Attribute	Description	Type	Default
addon	addon	An optional prop for the component to display prefix or suffix addon.	{ type: "prefix" | "suffix"; label: string; colorVariant?: "gray" | "white"; leftIcon?: string; rightIcon?: string; clickEvent?: () => void; options?: DhlSelectionOptionType[]; optionClickEvent?: (o: DhlSelectionOptionType) => void; }	undefined
autoComplete	auto-complete	An optional prop used to set the autocomplete value. It takes any valid value that can be used for the autocomplete attribute of an HTMLInputElement.	string	undefined
blurEvent	blur-event	[DEPRECATED] Use dhlBlur event instead. An optional onBlur callback handler.	(event: FocusEvent) => void	undefined
dataAriaActivedescendant	data-aria-activedescendant	An optional prop used to identify the currently active element within a composite widget context.	string	undefined
dataAriaAutoComplete	data-aria-auto-complete	An optional prop used to indicate whether inputting text could trigger display of one or more predictions of the user's intended value.	string	undefined
dataAriaDescribedby	data-aria-describedby	An optional prop defining the list of reference IDs (separated by spaces), recommended when you want to an error message on your field.	string	undefined
dataAriaExpanded	data-aria-expanded	An optional prop used for assistive technology support - used to mark expandable and collapsible regions.	string	undefined
dataAriaHasPopup	data-aria-has-popup	An optional prop that lets the screen reader know that this component has a popup.	string	undefined
dataAriaLabel	data-aria-label	An optional prop defining the text read by the screen reader to represent the component; use this if you need different text to be read from label.	string	undefined
dataAriaOwns	data-aria-owns	An optional attribute to identify an element (or elements) to define a visual, functional, or contextual relationship between a parent and it's child when it otherwise cannot be in the DOM hierarchy.	string	undefined
dataClassName	data-class-name	An optional class name prop for the component.	string	undefined
dataId	data-id	An optional prop. Gives a valid HTML ID attribute value for the component.	string	`dhl-input-field-${getRandomString()}`
dataRole	data-role	An optional prop defining the role attribute of the component.	string	undefined
dataTestid	data-testid	An optional prop. The test id attached to the component as a data-testid attribute.	string	undefined
dataTracking	data-tracking	An optional data tracking prop for the component.	string	undefined
decimalPoint	decimal-point	An optional prop to limit the number of decimal places allowed. Set to 0 to block decimals entirely, or a positive number to limit decimal places.	number	undefined
decimalSeparator	decimal-separator	An optional prop to define the decimal separator character. It accepts "," (comma) or "." (dot). When set, the input type becomes "text" to avoid browser validation issues, and all decimal values are automatically formatted to use the configured separator. Only applies when type="number".	"," | "."	undefined
disableValidation	disable-validation	An optional prop to disable the validation's visual feedback. Validation is still applied and validity state is still set to the form element.	boolean	false
focusEvent	focus-event	[DEPRECATED] Use dhlFocus event instead. An optional onFocus callback handler.	(event: FocusEvent) => void	undefined
formNoValidate	form-no-validate	An optional prop used to set native formnovalidate attribute. This bypasses form control validation for form submission for the types image and submit.	boolean	undefined
handleInputClear	handle-input-clear	An optional handleInputClear callback handler.	(e: Event) => void	undefined
inputEvent	input-event	[DEPRECATED] Use dhlInput event instead. An optional onInput callback handler.	(event: InputEvent) => void	undefined
isDisabled	disabled	An optional flag to define if the component is disabled.	boolean	false
keyDownEvent	key-down-event	[DEPRECATED] Use dhlKeyDown event instead. An optional onKeyDown callback handler.	(event: KeyboardEvent) => void	undefined
leftIcon	left-icon	An optional prop to define left icon.	string	undefined
leftImage	left-image	An optional prop to define left image under input label.	string	undefined
list	list	An optional attribute that specifies a datalist for the input field.	string	undefined
max	max	An optional prop describing the maximum value that can be entered in the input field. Only works with type="number".	string	undefined
maxDigits	max-digits	An optional prop to limit the number of digits allowed before the decimal point. Only works with type="number".	number	undefined
min	min	An optional prop describing the minimum value that can be entered in the input field. Only works with type="number".	string	undefined
name	name	An optional value to be set to the element HTML name attribute. It takes any valid value that can be used for the name attribute of an HTMLInputElement.	string	undefined
pattern	pattern	An optional prop describing the regular expression pattern that the input value must match.	string	undefined
readonly	readonly	An optional prop to flag the component as readonly within a form context.	boolean	false
required	required	An optional prop to flag the component as required within a form context.	boolean	undefined
rightIcon	right-icon	An optional prop to define right icon.	string	undefined
rightIconClickEvent	right-icon-click-event	An optional right icon click callback handler.	(e: Event) => void	undefined
rightIconColorVariant	right-icon-color-variant	An optional prop to define right icon color variant.	"error" | "inverted" | "note" | "primary" | "secondary" | "success" | "sustainability" | "warning"	undefined
showClearButton	show-clear-button	An optional prop flag to define if clear button is displayed	boolean	true
size	size	An optional size prop for the component.	"md" | "sm"	Sizes.MD
step	step	An optional prop describing the step value for the input field. It works with type="number".	string	undefined
tooltip	tooltip	An optional prop to display tooltip on right icon hover.	{ title: string; description: string; placement?: "top" | "bottom" | "left" | "right" | "none"; isMobileVariant?: boolean; }	undefined
type	type	An optional prop describing the type of the component. It takes any valid value that can be used for the type attribute of an HTMLInputElement.	string	"text"
validation	validation	An optional object to set-up a custom components validation state. Required Fields: type	{ type: "warning" | "valid" | "invalid" | "note"; message?: string; }	undefined
value	value	An optional prop defining the value of the component which is taken when a form is submitted.	string	""
variant (required)	variant	A REQUIRED object to set-up a custom components variant state. It can be used to set a custom label and a custom placeholder text. label is required. placeholder is optional. type property was removed because animated behavior of label and placeholder is no longer supported. When placeholder is not provided, then label stays permanently animated.	{ label: string; placeholder?: string; }	undefined

Events

Event	Description	Type
dhlBlur	Event emitted when the input field loses focus.	CustomEvent<{ value: string; }>
dhlChange	Event emitted when the input field changes value.	CustomEvent<{ value: string; }>
dhlFocus	Event emitted when the input field receives focus.	CustomEvent<{ value: string; }>
dhlInput	Event emitted when the input value changes.	CustomEvent<{ value: string; }>
dhlKeyDown	Event emitted when a key is pressed down on the input field.	CustomEvent<KeyboardEvent>
dhlKeyUp	Event emitted when a key is released on the input field.	CustomEvent<KeyboardEvent>

Methods

checkValidity() => Promise<boolean>

Checks the validity of the input field.

Returns

Type: Promise<boolean>

A promise that resolves to true if the input field is valid, otherwise false.

getInputElement() => Promise<HTMLInputElement>

Retrieves the input element asynchronously.

Returns

Type: Promise<HTMLInputElement>

A promise that resolves to the input element.

getValidationMessage() => Promise<string>

Retrieves the validation message for the input field.

Returns

Type: Promise<string>

A promise that resolves to a string representing the validation message.

reportValidity() => Promise<boolean>

Reports the validity of the input field.

Returns

Type: Promise<boolean>

A promise that resolves to a boolean indicating whether the input field is valid.

setValidity(validity: ValidityState, validationMessage?: string) => Promise<void>

Sets the validity state of the input field.

Parameters

Name	Type	Description
validity	ValidityState	- The validity state to set.
validationMessage	string	- An optional validation message to set.

Returns

Type: Promise<void>

A Promise that resolves when the validity state is set.

willValidate() => Promise<boolean>

Returns a promise that resolves to true if the element will successfully validate, or false otherwise.

Returns

Type: Promise<boolean>

A promise that resolves to a boolean value indicating whether the element will validate.

Slots

Slot	Description
"right-icon"	slot intended for a DhlIcon to be displayed within DhlInputField

Dependencies

Used by

• dhl-action-bar
• dhl-autocomplete-field
• dhl-dropdown
• dhl-navbar
• dhl-select

Depends on

• dhl-icon-wrapper
• dhl-icon
• dhl-input-addon
• dhl-label
• dhl-image
• dhl-popover
• dhl-text
• dhl-validation-feedback

Graph

---

Built by DHL User Interface Library Team!

Migrating from DUIL 1.0

• Rename onBlur to blurEvent
• Rename disabled to isDisabled
• Rename onChange to inputEvent
• rightIcon now supplied via slot name right-icon
• Remove prop ariaExpanded
• Remove isBlock
• Add formnovalidate
• Add dataAriaActivedescendant
• Add dataAriaAutoComplete
• Add dataAriaExpanded
• Add autoComplete
• Add dataAriaOwns
• Add focusEvent
• Add keyDownEvent
• Add dataRole