Migration to v2

This page contains a guide on how to migrate from ZUi web version 1 to version 2.
The old storybook of the last version 1 release can be found here: https://dizuiwebdocs.z1.web.core.windows.net/zui/release/v1/?path=/story/basic-colors--colors

Setup

React Setup

Before, it was sufficient to import react wrapper components from the @zeiss/zui-react package.

Starting with version 2 in addition to this you have to add an import '@zeiss/zui' in your central setup code (where you setup the themes). For other frameworks this has always been mandatory and now it's needed for react too. @zeiss/zui is now a peer dependency.

Deprecations

In the past we've done some changes in our components that were already marked as "deprecated". For most of these things, there were already alternatives available so if you've updated your code in the past, you are likely already safe. You can find a list of these deprecations here.

However, we didn't have the chance to mark all changes of V2 as deprecated so there are some things that have changes that were not known before and where no alternative was available before. These topics are described in this document below.

Names

The <zui-textfield>'s name was TextField, we unified it to Textfield, so you have to adjust its usage for both imperative usage and its React wrapper has been renamed as well from ZuiTextField to ZuiTextfield.

We also dropped support for deprecated component names:

• <zui-menu-bar> / MenuBar / ZuiMenuBar -> <zui-menubar>/ Menubar / ZuiMenubar
• <zui-menu-bar-item> / MenuBarItem / ZuiMenuBarItem -> <zui-menubar-item>/ MenubarItem / ZuiMenubarItem
• <zui-comment> / Comment / ZuiComment -> <zui-textarea>/ Textarea / ZuiTextarea

Removed components

• (internal) <zui-slider-basic> has been removed, use <zui-slider> instead
• <zui-ewi-dialog-light> has been removed, use <zui-ewiq-dialog> instead

Icons

With version 2 we've done a major rework of our icons. Before, they were delivered as part of the zui core package with only rare updates. From now on, there is a separate NPM package "@zeiss/zui-icons" which contains the icons only. It's build automatically based on the ZUi icons defined by the design team. Everytime the design team updates their icons, our pipeline will create a new release of zui-icons web components. This is totally unrelated to the release-cycle of zui core and happens roughly every two weeks.

@zeiss/zui-icons is a peer dependency for @zeiss/zui. You can use never versions of the icons, and as long as the design team is not doing any breaking changes, you should be good to go. We will update the peer dependency of @zeiss/zui-icons.

Setup

You have to add @zeiss/zui-icons to your dependencies. In addition you have to add an import '@zeiss/zui-icons' to your setup code for the icons to be available.

Icon Names

With this transition, the design team also defined new unified naming rules and categorization for icons with the positive effect that now many icons have a more precise naming without too much clutter and duplication. However, it also means that you will have to rename most icons in your application.

Here is a list of the old icon names: https://dizuiwebdocs.z1.web.core.windows.net/zui/release/Maintenance/?path=/story/icons--icon-overview And a list of new icons: https://dizuiwebdocs.z1.web.core.windows.net/zui/release/integration/?path=/story/icons--icon-overview for the latest peer dependency of ZUi.

icon sizes

We've also changed the size attribute of icons. Previously t-shirt sizes like "S", "M", "XL" were used. However, this turned out to be inflexible when new sizes in between existing had to be added. The new icons use size values that are aligned to the pixel size of the icons. However, there is still a fixed set of supported size values: s8, s12, s16, s24, s32, s40, s48, s64, s72, s80. We decided to use strings with a prefix "s" (for "size") to prevent users from mistaking the values for type number pixel values.

You will have to adjust your code to use new size values:

ZEISS logo

Previously, the ZEISS logo was also implemented as an icon <zui-icon-zeiss>. This is not the case anymore. The ZEISS logo is now a "normal" ZUi component zui-zeiss-icon as it has some special brand-related behavior compared to other icons.

React Icons

For react users we provide wrapper components for all ZUi web components. This is also true for the icons. Previously, these icon wrapper components were part of @zeiss/zui-react which is not the case anymore as the release-cycle of our components and the icons are now decoupled.

You have to add the new @zeiss/zui-react-icons package to your dependencies and change the imports to this package in your code.

Before:

import { ZuiIconCheckmark } from "@zeiss/zui-react"

After:

import { ZuiIconSymbolsCheckmark } from "@zeiss/zui-react-icons"

Portals

In the past we had several refactorings and changes regarding components that have some sort of "detached" elements, like the drop-down of zui-select, the picker of zui-textfield-date-picker and many others. Internally, we are using a system called "portals" for all these cases. With V2 we consolidated this system to be more robust when it comes to use-cases involving other third-party libraries. See Portals for more information on portals and how to use them.

In most cases, you don't have to care about portals because ZUi components handle them automatically. However, in some cases you might had to customize the behavior to match your specific use-cases, especially if you work with other third-party libraries for things like dialogs or if you have issues with parts of a ZUi component aren't visible in a dialog or popover.

In the past, several components supported a level attribute to adjust the portal level (think of it as a z-index) for individual components. This attribute is not supported anymore. Instead, the handling of the portal level is done with the css property --zui-portal-level only. This approach is way more flexible as you can define the css property on any DOM level in your app. Typically, you will have a global portal level for your whole app, i.e. add this code to your global stylesheet:

:root {
    --zui-portal-level: 1000;
}

This way, all ZUi components will use this level for their detached parts. In addition, you can specify a different level for individual components or groups of components by applying this css property with a css selector that fits your needs.

// Before

<zui-select class="some-class" level="1300"></zui-select>

// After

<style>
.some-class {
    --zui-portal-level: 1300;
}
</style>

<zui-select class="some-class"></zui-select>

N.B. This is currently not working yet.

List and Skeletons

In the past, our zui-list component had a "skeleton" feature were skeleton items were created in cases were actual date wasn't available yet (i.e. when you load items). However, this feature was hard to use and didn't work very well. For this reason we decided to deprecate this whole feature and it is removed from V2.

In the future, we will re-introduce a more general skeleton feature that's not limited to the list but will work with other ZUi components too. Until then, you should use normal list-items and style them so that they look like skeletons.

Events

We've done a major refactoring of our events logic. Previously, we didn't have a solid and consistent naming pattern for our events. And we also haven't had a consistent usage of event attributes like bubbles, composed and cancelable. With version 2, we've defined a solid pattern for our events and unified all events of all components. However, this unification means that events are renamed and you have to update your code to use the new event names.

The biggest change is that our events now have a zui- prefix, i.e. zui-menubar-item-selected. This way, we can prevent name clashes with other events and it's clear which events are related to ZUi components. The only exception to this rule are events that directly mimic standard HTML events like change or input.

Please see the list of supported events in the docs of the component in storybook. Here is a list of all components, that had events in V1 and how they changed in v2 (this list is autogenerated. If you find inconsistencies or errors, please contact us).

about-screen

zui-about-screen-closed -> new

box

close -> zui-box-closed
box-closed -> zui-box-closed

checkbox

no changes

content-accordion

content-accordion-open-state-changed -> zui-content-accordion-open-changed

content-accordion-details

content-accordion-details-open-state-changed -> zui-content-accordion-details-toggled

content-tab-bar

content-tab-item-closed -> zui-content-tab-bar-item-closed
content-tab-item-selected -> zui-content-tab-bar-item-selected

content-tab-default-item

content-tab-item-closed -> zui-content-tab-item-closed

content-tab-highlight-item

content-tab-item-closed -> zui-content-tab-item-closed

content-tab-image-item

content-tab-item-closed -> zui-content-tab-item-closed

date-picker

date-picker-current-date-changed -> zui-date-picker-current-date-changed
date-picker-date-selected -> zui-date-picker-date-selected

date-picker-day-picker

day-picker-day-selected -> zui-day-picker-day-selected
day-picker-month-selected -> zui-day-picker-month-selected
day-picker-next-month-selected -> zui-day-picker-next-month-selected
day-picker-previous-month-selected -> zui-day-picker-previous-month-selected
day-picker-weekday-selected -> zui-day-picker-weekday-selected

date-picker-input

date-picker-input-calendar-selected -> zui-date-picker-input-calendar-selected
date-picker-input-changed -> zui-date-picker-input-changed
date-picker-input-focused -> zui-date-picker-input-focused

date-picker-input-part

zui-date-picker-input-part-focus-next -> new
zui-date-picker-input-part-focus-previous -> new
date-picker-input-part-value-changed -> zui-date-picker-input-part-value-changed

date-picker-month-picker

month-picker-month-selected -> zui-month-picker-month-selected
month-picker-next-year-selected -> zui-month-picker-next-year-selected
month-picker-previous-year-selected -> zui-month-picker-previous-year-selected
month-picker-year-selected -> zui-month-picker-year-selected

date-picker-year-picker

year-picker-decade-selected -> zui-year-picker-decade-selected
year-picker-next-decade-selected -> zui-year-picker-next-decade-selected
year-picker-previous-decade-selected -> zui-year-picker-previous-decade-selected
year-picker-year-selected -> zui-year-picker-year-selected

dialog-box

accept -> zui-dialog-box-accepted
cancel -> zui-dialog-box-cancelled
close -> zui-dialog-box-closed

dialog-button

no changes

drag-drop-area

no_changes

headerbar

headerbar-searchbar-icon-selected -> zui-headerbar-searchbar-icon-selected

icon-bar

close -> zui-icon-bar-closed

list-accordion

list-accordion-open-changed -> zui-list-accordion-open-changed

menu-tab-bar

menu-tab-bar-selection-changed -> zui-menu-tab-bar-selection-changed

menubar

change -> removed
input -> removed
zui-menubar-selected -> new

menubar-nav-item

menubar-item-selected -> zui-menubar-item-selected

multi-item-slider-pagination

multi-item-slider-pagination-page-selected -> zui-multi-item-slider-pagination-page-selected

pagination-dot-bar

pagination-dot-bar-pagination-dot-selected -> zui-pagination-dot-bar-pagination-dot-selected

picker-grid

picker-header-cell-selected -> zui-picker-grid-header-cell-selected
picker-grid-cell-selected -> zui-picker-grid-cell-selected

picker-header

picker-header-current-selected -> zui-picker-header-current-selected
picker-header-next-selected -> zui-picker-header-next-selected
picker-header-previous-selected -> zui-picker-header-previous-selected

pill

close -> zui-pill-closed

portal

portal-ready -> zui-portal-ready

radio-button

no changes

radio-button-group

changed -> removed
blur -> no change
change -> no change
input -> no change

scrollbar

scrollbar -> zui-scrollbar-scrolled

searchbar

searchbar-filter-changed -> zui-searchbar-filter-changed
searchbar-filter-opened -> zui-searchbar-filter-opened
searchbar-input -> zui-searchbar-input
searchbar-input-blurred -> zui-searchbar-input-blurred
searchbar-input-focused -> zui-searchbar-input-focused
searchbar-input-selected -> zui-searchbar-input-selected
searchbar-result-selected -> zui-searchbar-result-selected
searchbar-results-closed -> zui-searchbar-results-closed
searchbar-results-opened -> zui-searchbar-results-opened

searchbar-input

change -> no change
input -> no change
searchbar-input-changed -> zui-searchbar-input-changed

select

changed -> removed
close -> zui-select-closed
open -> zui-select-opened
change -> no change
input -> no change

select-menu

select-menu-close -> zui-select-menu-close
select-menu-closed -> zui-select-menu-closed
select-menu-open -> zui-select-menu-open
select-menu-opened -> zui-select-menu-opened

slider

no changes

slider-custom

no changes

slider-range

no changes

textarea

no changes

textfield-date-picker

change -> no change
input -> no change
textfield-date-picker-date-selected -> zui-textfield-date-picker-date-selected

textfield-time-picker

change -> no change
input -> no change
textfield-time-picker-input-changed -> zui-textfield-time-picker-input-changed

time-picker

time-picker-changed -> zui-time-picker-changed
time-picker-input -> zui-time-picker-input

time-picker-cell

time-picker-cell-changed -> zui-time-picker-cell-changed
time-picker-cell-input -> zui-time-picker-cell-input

time-picker-day-time-toggle

time-picker-day-time-changed -> zui-time-picker-day-time-changed

time-picker-input

time-picker-input-changed -> zui-time-picker-input-changed
time-picker-input-input -> zui-time-picker-input-input
time-picker-input-toggle -> zui-time-picker-input-toggle

time-picker-input-part-day-time

time-picker-input-part-day-time-changed -> zui-time-picker-input-part-day-time-changed
time-picker-input-part-day-time-input -> zui-time-picker-input-part-day-time-input
time-picker-input-part-focus-previous -> zui-time-picker-input-part-focus-previous

time-picker-input-part-number

time-picker-input-part-focus-next -> zui-time-picker-input-part-focus-next
time-picker-input-part-focus-previous -> zui-time-picker-input-part-focus-previous
time-picker-input-part-number-changed -> zui-time-picker-input-part-number-changed
time-picker-input-part-number-input -> zui-time-picker-input-part-number-input

toast-notification

close -> zui-toast-notification-closed

toggle-bar

no changes

toggle-bar-button

toggle-bar-button-selected -> zui-toggle-bar-button-selected

toggle-switch

no changes