An image for design units.

Design units in 10.3

Published: June 24th, 2014

Read the documentation

Explore a new way to design your UIs

With the release of API level 10.3 for the BlackBerry 10 Native SDK, we've introduced some new features to help make it easier to design and build your apps. In this article, we take a look at design units, a new concept that's been added to Cascades to give you more flexibility than ever.

Design units let you create adaptable UIs more easily. Along with other features such as relative layouts, space quotas, and asset selection, design units help you create UIs that look good and scale well on a variety of BlackBerry 10 devices.

A design unit is a unit of measurement that's independent of any particular device or screen resolution. A single design unit corresponds to a different number of pixels depending on the device that the app runs on. For example, on a BlackBerry Z30 smartphone, one design unit corresponds to 8 pixels. On a BlackBerry Z10 smartphone, one design unit corresponds to 10 pixels. These mappings help make sure that your UI maintains proper spacing and scaling when your app is run on devices with different screen densities.

In our documentation, you might sometimes see design units abbreviated as "du".

Cascades automatically converts design units into pixel values that are optimal for the device that the app runs on. Here's a table that describes how design units translate to pixel values for each device.


Pixels per design unit

Width (du)

Height (du)

BlackBerry Z30 and BlackBerry Z3




BlackBerry Q10 and BlackBerry Q5




BlackBerry Z10




BlackBerry Passport




You can use design units to specify dimensions in your UI, such as the length and width of a control, the amount of space for a margin, and so on. You can check out QML Properties for more information about specifying dimensions and other properties. There are several conversion functions for design units that are available through the UIObject::ui property. The UIConfig object that this property returns contains three different conversion methods:

du() - design units
Converts a design unit into an explicit pixel value that's optimal for the pixel density of the device.
sdu() - snapped design units
Converts a design unit into an explicit pixel value that's optimal for the pixel density of the device, and rounds the amount to the nearest whole pixel.
px() - pixels
Converts a pixel value into an equivalent pixel value. This function doesn't change the pixel amount; it's a way to explicitly show that a dimension is measured in pixels. Generally, you should always try to use design units or snapped design units instead.

Here's how to create a simple UI using design units for padding and margin values instead of pixels:

import bb.cascades 1.3
Page {
    Container {
        topPadding: 16
        bottomPadding: 16
        rightPadding: 16
        leftPadding: 16

        TextField {
            hintText: "To:"
            bottomMargin: 54
        TextField {
            hintText: "Subject:"
            bottomMargin: 54
        TextArea {
            layoutProperties: StackLayoutProperties {
                spaceQuota: 1

Why use design units?

If you're already using pixel values in your apps and you're comfortable working with them, it might seem like a lot of work to switch to design units instead. There's really one main reason to use design units: an app that uses design units is able to retain its relative dimensions regardless of the screen density of the device that it runs on.

Consider the following scenario: you've designed your app UI with only earlier BlackBerry 10 devices in mind (BlackBerry Z10, BlackBerry Z30, BlackBerry Q10, and so on). Although these devices have different screen sizes, shapes, and resolutions, they all have a similar screen density that ranges from 295 dpi to 356 dpi. Because the screen densities are so similar, you can specify dimensions using real pixel amounts and still create a single UI that works well for all devices (if you follow other guidelines for resolution independence such as using relative layouts and space quotas). However, if you run the app on a device that has a much higher screen density, the pixel dimensions don't retain their relative size.

To learn more about design units, as well as other techniques to help you create adaptable UIs, take a look at Resolution independence in the Best Practices section of the documentation.