ActionBar

The DhlActionBar is a form component used to submit delivery action strings by end-consumers.

• Label & placeholder: Supports label (required) and placeholder (optional). When only label is provided, it acts as placeholder and animates to the top when typing.
• Enter key: Pressing Enter in the input triggers the search (emits dhlSubmit).
• Value persistence: The value prop is passed to the input; set it from URL or state to display after refresh.

Import

React

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

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

Angular

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

<dhl-action-bar></dhl-action-bar>

Vue.js

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

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

Code

React

<DhlActionBar></DhlActionBar>

Angular

<dhl-action-bar></dhl-action-bar>

Vue.js

<dhl-action-bar></dhl-action-bar>

Interactive Demo

action bar

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-action-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-action-bar
        name="action-bar-1"
        label="Enter your shipment number(s)"
        placeholder="Enter your shipment number(s)"
        button-text="Track"
      ></dhl-action-bar>
    </dhl-grid-cell>
  </dhl-grid-container>
</form>

label only (no placeholder)

When only label is provided without placeholder, the label acts as placeholder and animates to the top when the user types. Press Enter to trigger search.

<form novalidate>
  <dhl-action-bar
    label="Enter your tracking number"
    placeholder=""
    button-text="Track"
  ></dhl-action-bar>
</form>

label and placeholder

When both are provided, the label stays at the top and the placeholder appears in the input field.

<form novalidate>
  <dhl-action-bar
    label="Tracking number"
    placeholder="Enter your tracking number(s)"
    button-text="Track"
  ></dhl-action-bar>
</form>

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

<form novalidate>
  <dhl-grid-container columns="2">
    <dhl-grid-cell span-columns="2">
      <dhl-action-bar
        name="action-bar-1"
        label="Enter your shipment number(s)"
        placeholder="Enter your shipment number(s)"
        required
      >
      </dhl-action-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-action-bar
        name="action-bar-1"
        label="Enter your shipment number(s)"
        placeholder="Enter your shipment number(s)"
        required
      >
      </dhl-action-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 actionBarComponent = document.querySelector("dhl-action-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) {
      actionBarComponent.validation = {
        type: "valid",
        message: validationMessageValid,
      };
    } else {
      actionBarComponent.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-action-bar
        name="action-bar-1"
        label="Enter your shipment number(s)"
        placeholder="Enter your shipment number(s)"
        required
      >
      </dhl-action-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 actionBarComponent = document.querySelector("dhl-action-bar");

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

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

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

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

Properties

Property	Attribute	Description	Type	Default
blurEvent	blur-event	[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 action bar; use this if you need different text to be read from label This is particularly important when using icons within the Button.	string	undefined
buttonIcon	button-icon	An optional prop used to pass an icon to render by the children of the Button	string	undefined
buttonIconOrientation	button-icon-orientation	An optional prop used to align an icon (if present) on either the left or right side of the component.	Orientation.left | Orientation.right	DHL_BUTTON.ICON_ORIENTATION.RIGHT
buttonIconSize	button-icon-size	An optional prop used to control the size of icons in the button	Sizes.LG | Sizes.MD | Sizes.SM | Sizes.XL	DHL_BUTTON.ICON_SIZE.SM
buttonText	button-text	An optional prop used to set the text within the action bar submit button	string	"Action"
buttonVariant	button-variant	An optional prop used to set the text within the action bar submit button	Variants.ghost | Variants.ghostBlack | Variants.outline | Variants.outlineBlack | Variants.primary | Variants.text | Variants.tonal	DHL_BUTTON.VARIANT.PRIMARY
changeEvent	change-event	[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-action-bar-${getRandomString()}`
dataTestid	data-testid	An optional prop. The test id attached to the component as a data-testid attribute.	string	undefined
inputAriaLabel	input-aria-label	An optional prop defining the text read by the screen reader to represent the Input used within the action bar; 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
label	label	A REQUIRED prop used to set the label text. When provided alone (without placeholder), the label takes the placeholder position and animates to the top when the user types. When both label and placeholder are provided, the label stays at the top and the placeholder appears in the input field.	string	"Enter your shipment number(s)"
placeholder	placeholder	An optional prop used to set the placeholder text.	string	""
required	required	An optional prop to flag the component as required within a form context.	boolean	undefined
showClearButton	show-clear-button	An optional prop flag to define if clear button is displayed.	boolean	true
size	size	An optional prop to define the size of the component.	Sizes.MD | Sizes.SM	Sizes.MD
submitEvent	submit-event	[DEPRECATED] - Use dhlSubmit event instead An optional onSubmit callback handler	(event: MouseEvent) => void	undefined
validation	validation	An optional object to set-up a custom components validation state. Required Fields: type	{ type: Variants.warning | 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

Used by

• dhl-stage-tracking

Depends on

• dhl-input-field
• dhl-button

Graph

---

Built by DHL User Interface Library Team!