DocumentationAll ComponentsContact usChangelog
IntroductionAccessBug Reports and Feature RequestsContactInstallationAngularReactUsagePortalsData FormatsMobile and TouchFormsDepth levels and stacking contextsTool IntegrationHow to use SkeletonsMicrofrontends

Themes and Customization

ThemesCSS custom propertiesBuild Time ThemingFontsTool SupportMigrationguide and DeprecationsV3 to V4V2 to V3V1 to V2

Known Issues and Workarounds

Combobox initially open menu width not alignedSetting tabindex on disabled componentsTemplating into default SlotsTruncation limitation in title stackPopover position in small iframesStorybook problemsBrowser bugsFlex layout subsampling issueDead Keys in NumberInputsInteractive icon hitarea

Migration from V1 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.

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:

Old New
xs s8
s s12
m s16
l s24
xl s32
2xl s48
3xl s64
s72 (new)
4xl s80

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-selection-changed -> zui-menu-tab-bar-selection-changed

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

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-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

Deprecations in components

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.

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 the list below.

Avatar <zui-avatar>

The attribute imageUrl is deprecated, image-url should be used instead.

Box <zui-box>

Closing Behavior

The existing closing behavior of the box is unfavorable and will be reworked. Previously, the closing worked like this: When the attribute closable is set, the box shows a close button. When this button is clicked the attribute closed is set and the box will be hidden. However, the box is still part of the DOM tree. The same happens when the closed attribute is set programmatically.

This behavior has several drawbacks:

  • from a UI/UX perspective it's a inconsistent because you cannot get the box back to open.
  • it's unintuitive from a SPA developer perspective.

The more natural approach (and this is also the recommended approach from now on) is this:

  • when the close-icon is clicked, a close event is dispatched
  • besides this event, the box does nothing and stays the way it is
  • an SPA developer can react to this event and remove the box from the DOM/not render it anymore.

For this reason the closing behavior the way it was before is now deprecated. As an escape hatch if you need the previous behavior, you can set the new attribute use-deprecated-close-behavior to get back the old closing mechanism. Setting the closed attribute will then also work. However: In a future release this functionality will be dropped.

Emphasis

  • The emphasis active was renamed to selected. The old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Button <zui-button>

The emphasis active and active-primary were renamed to highlight and primary-highlight the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Date Picker components

Events in CamelCase style are depricated, instead the events with kebab-case style should be used.

<date-picker>

  • The event datePickerDateSelected is deprecated. Use date-picker-date-selected instead.

<date-picker-day-picker>

  • The event dayPickerDaySelected is deprecated. Use day-picker-day-selected instead.
  • The event dayPickerMonthSelected is deprecated. Use day-picker-month-selected instead.
  • The event dayPickerNextMonthSelected is deprecated. Use day-picker-next-month-selected instead.
  • The event dayPickerPreviousMonthSelected is deprecated. Use day-picker-previous-month-selected instead.
  • The event dayPickerWeekdaySelected is deprecated. Use day-picker-weekday-selected instead.

<date-picker-input>

  • The event datePickerInputCalendarSelected is deprecated. Use date-picker-input-calendar-selected instead.

<zui-date-picker-month-picker>

  • The event monthPickerMonthSelected is deprecated. Use month-picker-month-selected instead.
  • The event monthPickerNextYearSelected is deprecated. Use month-picker-next-year-selected instead.
  • The event monthPickerPreviousYearSelected is deprecated. Use month-picker-previous-year-selected instead.
  • The event monthPickerYearSelected is deprecated. Use month-picker-year-selected instead.

<zui-date-picker-year-picker>

  • The event yearPickerDecadeSelected is deprecated. Use year-picker-decade-selected instead.
  • The event yearPickerNextDecadeSelected is deprecated. Use year-picker-next-decade-selected instead.
  • The event yearPickerPreviousDecadeSelected is deprecated. Use year-picker-previous-decade-selected instead.
  • The event yearPickerYearSelected is deprecated. Use year-picker-year-selected instead.

<zui-textfield-date-picker>

  • The event textfieldDatePickerDateSelected is deprecated. Use textfield-date-picker-date-selected instead.

<zui-picker-grid>

  • The event pickerGridCellSelected is deprecated. Use picker-grid-cell-selected instead.
  • The event pickerHeaderCellSelected is deprecated. Use picker-header-cell-selected instead.

<zui-picker-header>

  • The event pickerHeaderPreviousSelected is deprecated. Use picker-header-previous-selected instead.
  • The event pickerHeaderCurrentSelected is deprecated. Use picker-header-current-selected instead.
  • The event pickerHeaderNextSelected is deprecated. Use picker-header-next-selected instead.

Dialog Button <zui-dialog-button>

The emphasis primary-active was renamed to primary-highlight the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Divider <zui-divider>

The emphasis moderate was renamed to default the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Ewi Dialog Light <zui-ewi-dialog-light>

The component is drepicated. Use <zui-ewiq-dialog> instead.

Interactive Icon <zui-interactive-icon>

The emphasis muted and moderate were renamed to to subtle and default the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

The attribute useDepricatedHitArea will be removed from the bundle in the next major version. The new Attribute for the same behavior is actually smallHitArea.

List <zui-list>

The automatic skeleton creating mechanic is deprecated, because it didn't worked very well and could only be used imperatively. It will get removed in version 2.

We are currently working on skeleton components which can be used with ZUi components. For now create yourself custom skeletons and put them as normal items into the zui-list.

<zui-menu>

  • The emphasis active and active-primary were renamed to selected and selected-primary the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

<zui-menu-item>

  • The emphasis active and active-primary were renamed to selected and selected-primary the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

The naming of the HTML-Tags from the Menu Bar and the Menu Bar Item was not consistent, so they got renamed.

  • <zui-menu-bar> is deprecated, use <zui-menubar> instead.
  • The emphasis active and active-primary were renamed to selected and selected-primary the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.
  • <zui-menu-bar-item> is deprecated, use <zui-menubar-item> instead.
  • The emphasis active and active-primary were renamed to selected and selected-primary the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

<zui-menubar-nav-item>

  • The event menubarItemSelected is deprecated. Use menubar-item-selected instead.
  • The emphasis active and active-primary were renamed to selected and selected-primary the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Progress Ring <zui-progress-ring>

The emphasis active and active-primary were renamed to to highlight and primary-highlight the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Select <zui-select>

The emphasis active and active-primary were renamed to selected and selected-primary the old emphasis will still be available in the upcoming releases but will be removed from the bundle in the next major version.

Title Stack zui-title-stack

The attribute wrapping will be deprecated after version 1.19.0. Use disable-wrapping with the inverted value instead.