TrackingBar

The DhlTrackingBar is a form component used to submit delivery tracking strings by end-consumers.

Import

React

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

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

Angular

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

<dhl-tracking-bar></dhl-tracking-bar>

Vue.js

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

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

Code

React

<DhlTrackingBar></DhlTrackingBar>

Angular

<dhl-tracking-bar></dhl-tracking-bar>

Vue.js

<dhl-tracking-bar></dhl-tracking-bar>

Interactive Demo

basic tracking bar

validated tracking bar

Please note the validation type property is required when specifying the validation object. Available variant types can be accessed as a field of TrackingBar through Variants.valid (see prop table for other available values) constant.

Migrating from DUIL 1.0

• Rename onBlur to blurEvent
• Rename disabled to isDisabled
• Rename onSubmit to submitEvent
• Rename onChange to changeEvent
• Remove isBlock

Readme

Usage

Dhl-tracking-bar

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

<form novalidate>
  <dhl-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-tracking-bar name="tracking-bar-1"></dhl-tracking-bar>
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

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

<form novalidate>
  <dhl-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-tracking-bar
        name="tracking-bar-1"
        required
      >
      </dhl-tracking-bar>
    </dhl-grid-cell>
    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    await e.target.checkValidity();
  });
</script>

usage with validation (required) and custom validation message

<form novalidate>
  <dhl-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-tracking-bar
        name="tracking-bar-1"
        required
      >
      </dhl-tracking-bar>
    </dhl-grid-cell>

    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  const trackingBarComponent = document.querySelector("dhl-tracking-bar");
  const validationMessageInvalid = "This field is invalid";
  const validationMessageValid = "This field is valid";

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

usage with custom events

<form novalidate>
  <dhl-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-tracking-bar
        required
        name="tracking-bar-1"
      >
      </dhl-tracking-bar>
    </dhl-grid-cell>
    <dhl-grid-cell>
      <dhl-button
        type="reset"
        variant="text"
        >RESET</dhl-button
      >
      <dhl-button
        type="submit"
        variant="primary"
        >SUBMIT</dhl-button
      >
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

<script type="module">
  const form = document.querySelector("form");
  const trackingBarComponent = document.querySelector("dhl-tracking-bar");

  const validationMessageInvalid = "This field is invalid";
  const validationMessageValid = "This field valid";
  const text = document.querySelector("dhl-text");

  const isElementValid = async () => {
    const isValid = await trackingBarComponent.checkValidity();
    if (isValid) {
      trackingBarComponent.validation = {
        type: "valid",
        message: validationMessageValid,
      };
    } else {
      trackingBarComponent.validation = {
        type: "invalid",
        message: validationMessageInvalid,
      };
    }
    return isValid;
  };

  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    await isElementValid();
  });

  trackingBarComponent.addEventListener(
    "dhlChange",
    async (e) => await isElementValid(),
  );
  trackingBarComponent.addEventListener("dhlBlur", async (e) =>
    isElementValid(),
  );
</script>

Properties

Property	Attribute	Description	Type	Default
blurEvent	--	[DEPRECATED] Use dhlBlur event instead. An optional onBlur callback handler.	(event: FocusEvent) => void	undefined
buttonAriaLabel	button-aria-label	An optional prop defining the text read by the screen reader to represent the Button used within the TrackingBar; use this if you need different text to be read from label This is particularly important when using icons within the Button.	string	undefined
buttonText	button-text	An optional prop used to set the text within the TrackingBar submit button	string	"Tracking"
changeEvent	--	[DEPRECATED] Use dhlChange event instead An optional onChange callback handler.	(event: InputEvent) => void	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
dataClassName	data-class-name	An optional class name prop for the component.	string	undefined
dataId	id	An optional prop. Gives a valid HTML ID attribute value for the component.	string	dhl-tracking-bar-${getRandomString()}
dataTestid	data-testid	An optional prop. The test id attached to the component as a data-testid attribute.	string	undefined
hasIcon	has-icon	An optional boolean flag prop used to indicate whether the TrackingBar submit Button is to render with an icon	boolean	false
inputAriaLabel	input-aria-label	An optional prop defining the text read by the screen reader to represent the Input used within the TrackingBar; use this if you need different text to be read from label	string	undefined
isDisabled	disabled	An optional flag to define if the component is disabled.	boolean	false
placeholder	placeholder	An optional prop used to set the placeholder text.	string	"Enter your shipment number(s)"
required	required	An optional prop to flag the component as required within a form context.	boolean	undefined
submitEvent	--	[DEPRECATED] - Use dhlSubmit event instead An optional onSubmit callback handler	(event: MouseEvent) => void	undefined
validation	--	An optional object to set-up a custom components validation state. Required Fields: type	{ type: Variants.valid \| Variants.invalid \| Variants.note; message?: string; }	undefined
value	value	An optional prop defining the value of the component which is taken when a form is submitted.	string	""

Events

Event	Description	Type
dhlBlur	Event emitted when the component loses focus.	CustomEvent<{ value: string; }>
dhlChange	Event emitted when the component changes value.	CustomEvent<{ value: string; }>
dhlSubmit	Event emitted when the component's button is triggered.	CustomEvent<{ value: string; }>

Methods

checkValidity() => Promise<boolean>

Checks the validity of the component.

Returns

Type: Promise<boolean>

A promise that resolves to true if the component 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 component.

Returns

Type: Promise<string>

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

reportValidity() => Promise<boolean>

Reports the validity of the component.

Returns

Type: Promise<boolean>

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

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

Sets the validity state of the component.

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.

Dependencies

Depends on

• dhl-input-field
• dhl-button
• dhl-icon-wrapper
• dhl-icon
• dhl-validation-feedback

Graph

---

Built by DHL User Interface Library Team!