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 Support

Migrationguide

V2 to V3V1 to V2DeprecationsDeprecations V3 to V4Deprecations V2 to V3Deprecations V1 to V2

Known Issues

Combobox initially open menu width not alignedSetting tabindex on disabled componentsTemplating into default SlotsTextfield type number, first minus entered will disappearTruncation limitation in title stackPopover position in small iframesStorybook problemsBrowser bugsFlex layout subsampling issueDead Keys in NumberInputsInteractive icon hitarea

Overview

While the focus of ZUi-Web always was browser applications on the desktop, they can also be used on touchscreen devices, like smartphones and tablets. For this, some adjustments are needed, to optimize our web components for these devices. For example, the components should become bigger, since that increases the accuracy of hitting the correct buttons on touchscreens. The components also get - if necessary - an increased hit-area for the exact same reason. Additionally, the font changes, for a better readability on smaller screens. At the moment, not all components have adjustments specifically for mobile/touch usage but over time we will add support to components where needed. In the storybook you will find a "mobile" badge for components that already implement mobile/touch features.

Why scale and touch-mode?

Initially, there was just one attribute, called "environment", which had touch, desktop and auto as possible values. But after some time thinking about it, we decided to split this one attribute into two: scale and touch-mode. Therefore, the environment attribute is deprecated, starting with ZUi-Web 3.4. The scale states the size of the screen, where the touch-mode indicates, if the used device has touch capabilities or not. The reason for this split is the fact, that ZUi-Web will be used on many devices that have a touchscreen, but anyways a rather big screen. There, it doesn't make sense to use styling, which was adapted for smaller mobile devices, just because they both work on a touchscreen. On the other hand, there are cases where a small screen is used but no touch capability is available, e.g. small browser window on desktop. Therefore we decided to use two attributes, that are independent from each other.

Scale

The scale attribute can have three values: desktop, mobile and auto. The default value for the scale is desktop. This should be used on big screens, and the style of the ZUi components will be the one you used so far. If mobile is selected, the components will be styled slightly different. First of all, the fonts differ from desktop. For a better readability on mobile devices, they got increased. Additionally, the components itself also got bigger, for example with newly added min-widths. If the attribute is set to auto, the provider sets the scale automatically, according to the screen width of the device. The breakpoint for that automatic switch is 786px. Overall, the scale attribute styles components in a way, that a good user experience can be ensured, no matter if the components are used on mobile devices or on tablets/devices with a bigger screen.

If you want to use the auto value for determining the scale, you need to insert the following line into the <head> of your app:

<meta name="viewport" content="width=device-width, initial-scale=1" />

Notice: The scale is not specific scale factor but instead just a switch for scale "modes".

Touch mode

The touch-mode attribute describes, which kind of screen will be used. Here, the possible values are touch, no-touch and auto. As the name suggests, if the device can and will be used with a touchscreen, this attribute has to be set to touch. Otherwise, no-touch has to be applied, which is also the default value. The auto value determines based on the "pointer" CSS media query, if touch or no-touch should be applied. The browser will set this media-query automatically depending on if the device has an accurate pointing device like a mouse or a pointing device with limited accuracy is used, such as touchscreen.

In the future, the touch-mode attribute will add an advanced hitarea, if necessary, to each component, that the hitarea for the users is at least 48px x 48px. At the moment, the hitareas are out of scope, which means the touch-mode attribute does not affect the components.

How to use the provider

The zui-provider is a new custom web component, that should be used to wrap your whole application inside. Somewhere at the top of your project, similar to the <zui-theme-provider>, insert the <zui-provider> as a wrapper. On t he zui-provider, you should specify the touch-mode attribute as well as the scale attribute for your project. If you do not specify these attributes, the default values will be applied, but we advise to not leave them empty.

The zui-provider is not intended for nested usage! We do not support nested usage at the moment, since it doesn't make sense. Either your application runs on mobile devices, or on devices with a bigger screen.

While the Scale can only be set on Provider level, the
Touch can be set on:
1. Component level
2. Provider level

With this, it is possible to deactivate the touch-mode for some specific components. This could be useful when you need to opt-out of the increased hitareas of 48px x 48px just for some specific components while the rest of the app still used the increased hitareas. It is possible to have multiple providers in parallel (without nesting them!).

Below is an example for the usage of the zui-provider. The second button has a different touch-mode:

<zui-provider touch-mode="touch" scale="mobile">
  <zui-button>Button</zui-button>
  <zui-button touch-mode="no-touch">Button</zui-button>
</zui-provider>

Fonts

The font variables (e.g. font: var(--zui-typography-h1), see Storybook font definitions) will be adjusted automatically based on the scale of the zui-provider. This means that if you're using those variables for your fonts, they will get bigger automatically on mobile devices.

As you can see in the following gif, the font changes automatically, according to the scale value:

Items.gif