Skip to main content

Upgrade Information

Install the React library11​

To use the latest features and components, install the DHL User Interface Library for React following the instructions in Getting Started for Developers

caution

All DUIL 1.0 components are now prefixed with Dhl e.g. Button is now DhlButton within Vue and React
In React, for example, Button is now DhlButton
In Vue & Angular, for example, Button is now dhl-button

Peer dependency​

  • styled-components are no longer needed as a peer dependency

Snapshot Testing​

Be aware that whilst the component interface strives for backwards compatibility, many components have been subject to markup changes. Please update your snapshot testing suits during migration.

Using Slots​

Composing components via children is a standard pattern in React. In React, components that support children will have a children prop that is then used in mark-up to reflect child nodes.

Web components achieve this through the use of <slot> tags, which reflect a placeholder for children nodes. Components which accept children nodes as part of their use-case are annotated as having unnamed slots within the documentation.

For example, the DhlIconWrapper supports an unnamed slot, intended to hold a DhlIcon.

before version 2.24​

import CalendarFridayEnglish from "@dhl-official/ui-libraries/assets/icons/calendar-friday-english.svg";

<DhlIconWrapper animation="spin">
  <DhlIcon src={CalendarFridayEnglish}></DhlIcon>
</DhlIconWrapper>;

from version 2.24​

import CalendarFridayEnglish from "@dhl-official/icons/calendar-friday-english.svg";

<DhlIconWrapper animation="spin">
  <DhlIcon src={CalendarFridayEnglish}></DhlIcon>
</DhlIconWrapper>;

As a consumer, simply place your element as a child of a parent that has an unnmamed slot.

Named slots​

Within React, one common pattern used to ensure flexibility in component composition is using "Compound Components". This is common in components such as Card, where you might use the Compound Components Card.Header, Card.Body and Card.Footer. This pattern is supported within the DUIL through named slots, a native approach supported by all output frameworks including React.

Components which support named slots specify the name of the slot and it's intended use on their respective documentation page.

For example, the DhlCard supports named slots header, footer and image to apply stylings unique to these sections.

<DhlCard>
  <img
    slot="image"
    src={img320x200}
    width="100%"
    style={{ display: "block" }}
    alt="A 320x200 sample yellow image"
  />
  <DhlHeadline
    slot="header"
    designLevel="4"
    noMargin
  >
    Header
  </DhlHeadline>
  <DhlText>
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo
    ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis
    parturient montes, nascetur.
  </DhlText>
  <div slot="footer">
    <DhlButton>Button</DhlButton>
  </div>
</DhlCard>

Global Attribute Changes​

The following global attributes used in DHL User Interface Library 1.0 require a data prefix in DHL User Interface Library 2.0 as shown below:

  • Rename prop ariaActivedescendant to dataAriaActivedescendant
  • Rename prop ariaAtomic to dataAriaAtomic
  • Rename prop ariaAutoComplete to dataAriaAutoComplete
  • Rename prop ariaControls to dataAriaControls
  • Rename prop ariaDescribedby to dataAriaDescribedby
  • Rename prop ariaDisabled to dataAriaDisabled
  • Rename prop ariaExpanded to dataAriaExpanded
  • Rename prop ariaOwns to dataAriaOwns
  • Rename prop ariaHasPopup to dataAriaHasPopup
  • Rename prop ariaHidden to dataAriaHidden
  • Rename prop ariaInvalid to dataAriaInvalid
  • Rename prop ariaLabel to dataAriaLabel
  • Rename prop ariaLabelledby to dataAriaLabelledby
  • Rename prop ariaLive to dataAriaLive
  • Rename prop className to dataClassName
  • Rename prop id to dataId
  • Rename prop title to dataTitle
  • Rename prop lang to dataLang
  • Rename prop role to dataRole

Deprecated theming functions​

Components​

The following list describes removed properties, renamed properties and new properties for affected components alongside other notable changes.

For example code snippets and interactive demos, visit the Components tab.

caution

Please note the removal of the isBlock property in the following components:

  • AutocompleteField
  • Counter
  • Dropdown
  • GlobalValidation
  • InputField
  • InputGroup
  • SelectableCard
  • Slider
  • TextAreaField
  • TrackingBar

We recommend using a GridContainer and GridCell components for positioning elements in your layout. This ensures that components take up only a specific portion of the available width, providing better layout control and responsiveness.

Accordion​

  • The AccordionContent component is replaced by DhlPanel.

  • Remove AccordionTitle. The title is now set on child element within Accordion via slot="heading" - see Accordion docs for snippet.

  • Rename showExpandCollapseButton to buttonOnly

  • Remove activeIndex

  • Remove focusedIndex

  • Remove onTitleClick

  • Remove buttonSize

  • Remove iconSize

  • Remove closeAlsoOnContentClick

  • Remove expandButtonAriaLabel and collapseButtonAriaLabel -> content of expanding/collapsing button is determined by consume.

  • Remove useAsCollapsible

  • Remove expandButtonAriaControls -> aria-controls set through heading and panel id props.

  • Remove expandIcon and collapseIcon prop

  • Add headingId & panelId

  • Button variant available through buttonOnly set prop;

    • headlineAlignment -> buttonAlign

  • Limit Headline style to only expose headlineTag within Accordion:

    • Remove weight prop
    • Remove size prop

AutocompleteField​

  • Rename onBlur to blurEvent
  • Rename onChange to inputEvent
  • Rename onOptionSelected to optionSelected
  • Rename ariaDescribe to dataAriaDescribedby
  • Remove renderOption
  • Remove isBlock

BackToTop​

  • Rename onClick to clickEvent
  • Rename onScrollComplete to scrollCompleteEvent

Button​

  • Rename onClick to clickEvent
  • Rename onKeyPress to keyPressEvent

Card​

  • Compound components e.g. Card.Header are now defined through slots (see docs)
  • Add dataTestid

Checkbox​

  • Rename onChange to changeEvent
  • Rename disabled to isDisabled
  • Add formnovalidate

Chip​

  • Rename disabled to isDisabled

Rename Controls to Counter​

  • Rename onChange to changeEvent
  • Rename onBlur to blurEvent
  • Rename disabled to isDisabled
  • Default inputmode is decimal
  • Add formnovalidate
  • Add min and max for setting Counter numerical limits
  • Remove isBlock

DatePicker​

  • Aria labels now passed through required localeLabels prop - please see documentation for all available aria fields found within this object.
  • Rename firstDayOfTheWeek to firstDayOfWeek
  • Remove date
  • Remove externalValidation
  • Rename minDate to min
  • Rename maxDate to max
  • Remove isBlock
  • Remove variant
  • Remove displayFormat see new prop dateAdapter for new implementation
  • Add dataAriaLabelledby
  • Add inputLabel
  • Add isDisabled
  • Add role
  • Add direction
  • Add dateAdapter
  • Add isDateDisabled
  • Add dhlChange
  • AdddhlBlur
  • Add new event dhlChange
  • Add new event dhlFocus
  • Add new event dhlOpen
  • Add new event dhlClose
  • Add public method setFocus
  • Add public method show
  • Add public method hide
  • Options are now passed to data prop, passing options as children/childNodes in no longer supported.
  • Rename disabled to isDisabled
  • Rename onChange to changeEvent
  • Rename onClick to clickEvent
  • Rename onClose to closeEvent
  • Rename onFilterChange to filterChangeEvent
  • Rename onOpen to openEvent
  • Rename ariaDescribe to textDescribe
  • Now a required prop: dataId
  • Now a required prop: name
  • rightIcon now only supports string, a path to the icon or data url for the icon
  • Consumer to handle the filtration of the options on filterChangeEvent
  • Remove isBlock

Flex​

  • No longer supports responsive value array.

GlobalValidation​

  • Separated into two components - DhlGlobalValidation & DhlIllustratedValidation for the icon variant and illustration variant
  • The variant prop now refers to valid and invalid states
  • Rename type to variant
  • Remove iconSize. The icon automatically scales in mobile viewport.
  • Rename text to message
  • To use illustrated variant, use GlobalIllustratedValidation component

Headline​

  • Rename fontStretch to stretch

Icons​

  • Import SVG and use in combination with the component:

before version 2.3.0​

import CalendarFridayEnglish from "@dhl-official/ui-libraries/stencil-library/dist/icons/calendar-friday-english.svg";
<DhlIcon name={CalendarFridayEnglish}></DhlIcon>;

or

import {
  CalendarFridayEnglish,
  CalendarFridayGerman,
} from "@dhl-official/ui-libraries/assets/icons";
<DhlIcon name={CalendarFridayEnglish}></DhlIcon>;
<DhlIcon name={CalendarFridayGerman}></DhlIcon>;

from version 2.3.0​

import CalendarFridayEnglish from "@dhl-official/icons/calendar-friday-english.svg";
<DhlIcon name={CalendarFridayEnglish}></DhlIcon>;

or

import {
  CalendarFridayEnglish,
  CalendarFridayGerman,
} from "@dhl-official/icons";
<DhlIcon name={CalendarFridayEnglish}></DhlIcon>;
<DhlIcon name={CalendarFridayGerman}></DhlIcon>;
danger

Previous version of this documentation reported the below import path to use icons.
Note this is now deprecated and will be soon removed, please update your imports to the new one above.

import CalendarFridayEnglish from "stencil-library/dist/stencil-library/assets/calendar-friday-english.svg";
<DhlIcon name={CalendarFridayEnglish}></DhlIcon>;

IconWrapper​

  • Rename animate to animation
  • Rename speed to duration
  • Update values of prop speed from SLOWER to "5x", SLOW to "4x", STANDARD to 3x", FAST to "2x"
  • Add dataClassName

Illustrations​

  • Moved to Icons and pre-fixed with illu-

InputField​

  • 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

InputGroup​

  • rightIcon only supports string, a path to the icon or data url for the icon
  • Rename disabled to isDisabled
  • Remove isBlock

Image​

  • Rename srcSet to srcset
  • Remove withButtonStyle prop object: isBlock, size and variant are now directly applicable
  • Add dataTitle

Logos​

  • Now implemented through Icons
  • Rename onClose to handleOnClose
  • Rename isStatic to trapFocus
  • handleOnShow and handleOnClose now optionally return the dialog element and the event
  • Add handleOnShow prop for function call when dialog open
  • The popover prop now takes a string instead of a (popover) node
  • Remove navActions
  • SearchData simplified to a link - to be refactored once designs updated
  • If items are not supplied to the mobileNavigationItems prop, Navbar will auto-generate items based on primaryNavigationItems and the headline property.

Page Headline​

  • Remove mainHeadlineContent, the content to be passed as children of the component
  • Remove subHeadlineContent, the content to be passed as children to the named slot subHeadline
  • Add hasSubHeadline to mention if the sub heading content is passed
  • Remove marginBottom

Popover​

  • Discontinue use of Popper.js.
  • Update placement to hold values top, right, bottom and left
  • Add useLabelledby
  • Remove offset
  • Remove popperOptions
  • Remove popoverTriggerAriaLabel
  • Remove showCloseButton
  • Remove closeButtonAriaLabel
  • Remove heading
  • Remove trigger
  • Remove closeOnOutsideClick

ProgressIndicator​

  • Rename onClickHandler to clickEvent

RadioButton​

  • Rename onChange to changeEvent
  • Rename disabled to isDisabled
  • Add formnovalidate

SelectableCard​

  • Rename onChange to changeEvent
  • RemoveisFullBleed
  • Remove isBlock
  • Add formnovalidate

Slider​

  • Remove validation
  • Remove isBlock
  • Rename color to colorVariant
  • Rename disabled to isDisabled
  • Steps can now be used without graphic indicator - to toggle, use showStep/show-step

Stage​

  • Stage.Actionbox changed to dhl-stage-action-box
  • Stage.Intro changed to dhl-stage-intro
  • Stage.Numbers changed to dhl-stage-numbers
  • Stage.Tiles changed to dhl-stage-tiles
  • Remove Stage.AddShipmentLink
  • Remove Stage.TrackingBar, use dhl-tracking-bar with margin: var(--dui-size-space-8x) 0;
  • stageLink content is rendered in named slot link
  • stageCopyText only supports string
  • upperHeadlineText only supports string
  • mainHeadlineText only supports string
  • When rendering numbers variant, the DhlStageNumbers have to be rendered twice, once as direct children and in named slot numbers to achieve responsiveness for larger screens

Stage.Actionbox​

  • headline prop changed to use named slot headline
  • subline prop changed to use named slot subline
  • icon prop now expects an icon relative or data path
  • Link content is rendered in named slot stageLink

Stage.Tiles​

  • mainHeadlineText now only supports string
  • pseudoLinkText now only supports string
  • upperHeadlineText now only supports string

Switch​

  • Rename onChange to changeEvent
  • Rename disabled to isDisabled
  • Rename color to variant prop

Table​

  • Now a required prop: columns
  • Rename field align to text-align within the rowData prop

Tabs​

  • Rename onChange to changeEvent
  • Prefix props label and disabled with data on li elements
  • Remove custom labels

TextAreaField​

  • Rename disabled to isDisabled
  • Remove isBlock

TrackingBar​

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

Validation Feedback​

  • Rename Validation type to DhlValidationFeedbackValidationType