Links
Comment on page

Widget Commonalities

While working with widgets, you may find some features or properties that are common in widgets. This page describes how to add features or change the properties that work in a similar fashion for several widget.
Here are they:

Use keyboard to increase/decrease property value

You can adjust the property value using your keyboard's up and down arrow keys. Tip: Use the shift key in combination with the arrow keys, which increments or decrements the value by 10 units at a time.

Widget Styling

Visibility

Conditional

Responsive

Responsive visibility is a feature that allows you to control the visibility of a widget based on the size of the screen or device being used. This means that you can create different versions of your UI for different screen sizes or device types, making sure that your app looks appropriate on each platform.
Here's an example of showing the different navigation menus on the web and mobile:
The navigation menu on the web and mobile
You can achieve this by creating two separate widgets and setting their responsive visibility (under the properties panel).
In the example above, the navigation menu created for the web or desktop (on the left side) is made visible only on a wider screen by enabling the desktop icon. Similarly, the navigation menu for the mobile (on the right side) is made visible only on a small screen by enabling the mobile icon.
Here is how it is done:
Responsive visibility for mobile
Responsive visibility for web

Customize responsive breakpoint

Sometimes you might want to override the default responsive breakpoint to suit unique requirements, whether it's accommodating a specific device or catering to a particular user experience, having the flexibility to customize breakpoints can be advantageous.
To customize responsive breakpoints, open Theme Settings (from the navigation menu) > Design System > Breakpoints and change the values.
For example, If you define a custom breakpoint at 575 pixels, positioning it between the 'Mobile' and 'Tablet' range. In this case, when your app is accessed on a screen larger than 575 pixels, the layout will be adjusted as per the Tablet configuration.
Customize responsive breakpoint

Opacity

Controlling the opacity of any widget opens up a plethora of creative opportunities. For instance, you can create an aesthetically pleasing effect using transparent buttons, dynamic themes, overlay effects, etc.
You can control the transparency from Properties Panel > Visibility > Opacity property. It accepts value between 0 to 1. e.g., 0 means full transparent, 1 is opaque, and 0.5 is half transparent.
Widget opacity

Padding & Alignment

Add padding

Padding is the empty space around the outer side of the widget.
To add a padding:
  1. 1.
    Select the widget from the widget tree or from the canvas area.
  2. 2.
    Move to the Property panel and navigate to the Padding & Alignment section.
  3. 3.
    Enter the L(left), T(top), R(right), B(bottom) values.
  4. 4.
    You can use the (
    ) Lock button to change all values together and refresh button(
    ) to reset the values.
Add padding
If you prefer watching a video tutorial, here is the guide for you:

Adjust alignment

This property helps you position the widget in two ways.
Horizontal Alignment determines where the widget will be placed horizontally inside of its parent. A value of -1 will place the widget to the left, while a value of 1 will place the widget to the right.
Vertical Alignment determines where the widget will be placed vertically inside of a parent. A value of -1 will place the widget at the top, while a value of 1 will place the widget at the bottom.
To change the alignment:
  1. 1.
    Select the widget, and head over to Properties Panel > Padding & Alignment section.
  2. 2.
    Use the alignment box to align the widget at a fixed position or directly enter a value in the Horizontal and Vertical input box.
Align the widget
If you prefer watching a video tutorial, here is the guide for you:

Testing

This section enables you to specify the Value Key for the current widget, which serves as a reference point during automated test runs. Please refer to the detailed guide provided here.

Changing the size

Use the instructions below to change the height or width of any widget.
  1. 1.
    Navigate to the Height or Width property of the widget.
  2. 2.
    There are three ways you can change the size:
    1. 1.
      To set to an exact size, select PX and enter the desired value.
    2. 2.
      To make the height or width of the widget the screen's height or width, click on the infinity icon (
      ).
    3. 3.
      To set the size as a % of the screen size, select % and enter the desired value.
Changing the size

Sizing widgets inside Column & Row

When you have multiple widgets inside the Column or Row, you might want to adjust their size based on the available space in the vertical or horizontal direction, assign a specific proportion to each widget, and ensure adaptability across different screen sizes.
You can distribute the space available inside the Column or Row using the following options:
  • Flexible (
    ): With this option, the widget is first displayed as per the given width and height and expands up to the available space (i.e., horizontal for Row and vertical for Column).
  • Expanded (
    ): This option expands the widget to fill the available space (i.e., horizontal for Row and vertical for Column), ignoring the widget's width and height.
  • Flex: This option is only available when there are multiple widgets and the Flexible or Expanded option is set. This option determines the proportion of space given to each widget. For example, if Widget A has Flex = 1 and Widget B has Flex = 2, then A will take up 1/3 of the available space, and B will take up 2/3 of the space.
  • When using the Flexible or Expanded option, make sure to limit the height of the Column and width of the Row. Using an unbounded Column or Row with a Flexible or Expanded option will break your application.
  • Please note that scrollable Columns and Rows are unbounded, so they should not be combined with expanded widgets.
To size widgets inside of Column or Row:
  1. 1.
    Select the widget and then select the sizing option: Flexible or Expanded.
  2. 2.
    Try adding Flex value, such as Widget A Flex = 1 and Widget B Flex = 2.
Flexible
Expanded
Making widgets Flexible
In the visual above, when setting the Flexible option, see how the widgets are first displayed with specified height and then stays in propertion when height is incresed.
Making widgets Expanded
In the visual above, when setting the Expanded option, see how the widget's height is ignored.
If you prefer watching a video tutorial, here is the guide for you:

Change color

To change color for any widget property:
  1. 1.
    Navigate to a widget property that allows you to set a color.
  2. 2.
    Click on the box next to Unset or already selected color, select the color, and then click Use Color or click on Unset or already selected color and enter a Hex Code directly.
  3. 3.
    You can also set a color from variable.
Change color

Opening Drawer from an AppBar

To open the Drawer (without an AppBar widget), you have to swipe on the page. This could be a little confusing to users since they don't have any signal that the Drawer exists. This can be solved by adding the AppBar widget. Once you add the AppBar, the AppBar automatically shows the menu icon (icon with three lines) button.
To add an AppBar:
  1. 1.
    Select the Page Name from the Widget Tree.
  2. 2.
    Drag the AppBar widget from the Page Elements tab (in the Widget Panel) or add it directly from the widget tree.
Opening the Drawer widget by clicking the menu icon in the AppBar:
Opening the EndDrawer:

Styling text

To stylize the text you can use any predefined style or create the custom one. Here' how you do it:
Example of styling text on Text widget
For consistency, we recommend creating your custom text styles before starting your project.

Changing line height

Sometimes you might want to make manual adjustments to the height of the Text line.
To change the line height of a text, move to the properties panel and find the Line Height (ratio) property and enter the value. (e.g. a value of 1.5 would make the line height 50% larger than the font size.)
Changing line height

Set max lines

When you have a long text that won't fit in a single line, it will start from the new line. You can limit your text up to certain lines if you wish to. For example, initially showing the product information up to a few lines.
To set the max lines:
  1. 1.
    Select Text from the widget tree or the canvas area.
  2. 2.
    Move to the Property panel (on the right side of your screen) and scroll down to the Text Properties section.
  3. 3.
    Find the Max Lines property and enter the value.
Set max lines

Adjust letter spacing

To adjust the spacing between the letters, move to the properties panel, find the Letter Spacing property and enter the value.
Adjust letter spacing

Changing Image type

By default, the widget is set to an Image Type of Network. However, you can change this to use an image uploaded directly to your app.
Here's how you can change the Image Type:
  1. 1.
    Select the widget from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Image section.
  3. 3.
    Find the Image Type dropdown. Click on Network (inside the dropdown) and select Asset.
  4. 4.
    Now, find the Asset Image property, Click on the Upload Image button, select the image, and upload it. Tip: You can also drag and drop the image directly inside the builder to upload.
If you want to use the same image multiple times in your app, you don't need to upload the same image multiple times. You can use the uploaded image for other Image widgets as well.
Once you upload an image, you can use it throughout your app. You can manage your uploaded images with the Project Media Asset Manager.
To use an uploaded image:
  1. 1.
    Select the widget from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Image section.
  3. 3.
    Find the Image Type dropdown. Click on Network (inside the dropdown) and select Asset.
  4. 4.
    Click on No asset select (inside the dropdown) and choose the image.

Showing Image on fullscreen

The displayed image might look small on some devices. You can allow users to see the image on a full screen and then zoom/pan the image by making the image Expandable.
To make the image expandable:
  1. 1.
    Select Image or CircleImage from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Image section.
  3. 3.
    Checkmark the Make Expandable property (click on it).
  • The zoom/pan image feature works only on a mobile device.
  • Checking the Make Expandable will add an Expand Image Action on the Image. See more details about the Expand Image Action here.

Set dark mode image

You can display a dark mode version for any image in your app. This is particularly useful when you want to improve the user experience by displaying an alternate image when the user switches to dark mode. For instance, showing a dark version of your app's logo that blends seamlessly with the app's dark mode interface, like this:
Dark mode image
To set dark mode version of your image:
  1. 1.
    Select the Image widget > move to the Properties Panel > set Image Type to Asset.
  2. 2.
    Enable Set Dark Mode.
  3. 3.
    Select the Light Mode Asset and Dark Mode Asset. You can upload images directly from here as well.
Set light and dark mode images

Customizing Icon

Here's how you can customize the icon:
  1. 1.
    To change the default icon, navigate to the Properties Panel > find the Icon property > Click on the default icon > search and select the icon.
  2. 2.
    To change its size, use the Icon Size property.
  3. 3.
    To change its color, use the Icon Color property.
Customizing Icon

Styling ListTile

Changing background color

To change the background color:
  1. 1.
    Select ListTile from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Style Properties section.
  3. 3.
    Find the Color property, click on the box next to #f5f5f5, select the color, and then click Use Selected Color. Or click on #f5f5f5 and enter a Hex Code directly. You can also choose the color by clicking on the Palette and Simple button.

Add content padding

Content Padding adds space between the item content and the border of your ListTile.
To add the content padding:
  1. 1.
    Select ListTile from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Style Properties section.
  3. 3.
    Find the Content Padding property and enter the values for L(left), T(top), R(right), and B(bottom) input boxes.

Reducing ListTile height

When you have a long list and you want to fit more content on the screen, you can use the dense property to reduce the height of the ListTile a bit.
To reduce the height:
  1. 1.
    Select ListTile from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Style Properties section.
  3. 3.
    Checkmark the Dense property (click on it).

Customizing ListTile title

To customize the title:
  1. 1.
    Select ListTile from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Title section.
  3. 3.
    Find the Theme Text Style dropdown. Click on Body Text 1 (inside the dropdown) to see other options and choose any.
  4. 4.
    Click on the button below the Font Family. Choose the font from the list. If the list doesn't contain the font you are looking for, you can search for it.
  5. 5.
    To change the size, enter the value in the Font Size property.
  6. 6.
    Now, find the Text Color property, Click on the box next to the already selected color, select the color, and then click Use Selected Color. Or click on the already selected color and enter a Hex Code directly. You can also choose the color by clicking on the Palette and Simple button.

Customizing ListTile subtitle

To customize the subtitle:
  1. 1.
    Select ListTile from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Subtitle section.
  3. 3.
    Find the Theme Text Style dropdown. Click on Body Text 1 (inside the dropdown) to see other options and choose any.
  4. 4.
    Click on the button below the Font Family. Choose the font from the list. If the list doesn't contain the font you are looking for, you can search for it.

Add ListTile leading icon

The Leading Icon appears at the start (left side) of the ListTile.
Here's an example of how you can add a leading icon:
  1. 1.
    Select ListTile from the widget tree or from the canvas area.
  2. 2.
    Move to the Property Editor (on the right side of your screen) and scroll down to the Leading Icon section.
  3. 3.
    Click on the None button then search and select the icon name from the image picker popup.
  4. 4.
    Set the Icon Size by entering the value in the Icon Size property.
  5. 5.
    To change the color, find the Icon Color property, click on the box next to Unset, select the color, and then click Use Selected Color or click on Unset and enter a Hex Code directly. You can also choose the color by clicking on the Palette and Simple button.

Adding border

To add border to any widget:
  1. 1.
    Find the Border Color property, and change the color using the intructions here.
  2. 2.
    To create the rounded border, use the Border Radius property. By default, any value your enter will be set for all corners, which are TL (Top left), TR (top right), BL (bottom left), and BR (bottom right). Click on the lock icon (
    ) to change each corner separately. Use the refresh icon to reset the values.
  3. 3.
    To increase the border thickness, use the Border Width property.
Adding border

Adding action

Actions help in handling user gestures inside the app. Some of the common Actions that you can define include On Tap, On Double Tap, On Long Press, On Submit, and so on.
To add an action:
  1. 1.
    Select the widget from the widget tree or from the canvas area.
  2. 2.
    Click on the Actions tab (on the right side of your screen).
  3. 3.
    Click on + Add Action and select any action from the On Tap, On Double Tap, On Long Press.
  4. 4.
    Select the Action Type from the dropdown menu.
  5. 5.
    Further options are displayed based on the Action Type you selected.
You can find a full list of Action Types here.

Enable pull to refresh

For some reason, you might have enabled the Single Time Query while making a Backend Query on a scrollable widget. This does not refresh the list if the item is updated in the backend. In such a case, you can add a pull-to-refresh feature.
Pull to refresh is a user interface pattern that allows users to manually refresh content by pulling or dragging the content area (usually a list or feed) downward. Once the content has been pulled down sufficiently, and then released, the app will refresh the content, fetching the latest data or updates.
Pull to refresh on ListView
To enable pull to refresh:
  1. 1.
    Select the ListView/GridView/StaggeredView from the widget tree or the canvas area.
  2. 2.
    Move to the properties panel and select the Backend Query.
  3. 3.
    Scroll down through the already added query (e.g. Query collection or API call) and make sure the Single Time Query is enabled.
  4. 4.
    Find the Enable Pull to Refresh property and turn on the toggle. This will automatically add the Refresh Database Request action on a pull to refresh gesture.
Enable Pull to Refresh on ListView

Setting color from variable

You might need to set a dynamic color to any widget property such as Container background and Text color. You can do so by setting a color from a variable. For example, displaying the temperature color based on or directly from a app state variable, Firestore document, API call response, or any other source.
Setting color from variable
To set a color from a variable:
  1. 1.
    Navigate to a widget property that allows you to set a color.
  2. 2.
    Click on the Set. This will open the Set from Variable menu.
  3. 3.
    From this menu, you can select the source of your color. For example, to set it from an app state variable, choose the App State -> variable name.
Setting color from variable
Here is another example of setting the color from Conditional Value.

Trigger action on selection change

Here you will see how to trigger an action when the selection changes for any Form widget such as Dropdown, RadioButton, ChoiseChips, Slider, and RatingBar.
For simplification purposes, we have used the Dropdown widget. The instructions go the same for the other Form widgets.
Triggering snackbar message on dropdown selection change
To do so:
  1. 1.
    Select the widget from the widget tree or canvas area.
  2. 2.
    Select Actions from the Properties panel (the right menu), and click + Add Action.
  3. 3.
    You will notice that the Type of Action (aka callback) is already set to On Selected. That means actions added under this will be called whenever the selection changes.
  4. 4.
    Now you can add any action here.
Here is an example showing the snackbar message when the Dropdown selection changes.
Triggering snackbar message on dropdown selection change

Copy variable

If you have set a complex variable value (e.g., using Conditional Logic) and want to use the same logic to set another variable value, you can do so by copying a variable.
To copy-paste a variable:
  1. 1.
    Open the Set from Variable menu and select the Variable Options icon.
  2. 2.
    Select the Copy Variable.
  3. 3.
    Move to the place where you want to paste the variable, and open the Set from Variable menu.
  4. 4.
    Click on the Paste Variable icon.
  5. 5.
    Click Confirm.
Copy variable

Combine text

Using this you can combine multiple texts that look like one. For example 'you have 3 notifications' text is a combination of 3 different texts, where 'you have' and 'notifications' are static texts, and '3' is a dynamic value from a variable.
Here's how you can display a combined text:
  1. 1.
    Select the widget property that can show a text (e.g., Text, TextField).
  2. 2.
    Click Set from Variable and select Combine Text.
  3. 3.
    To show the static text, directly enter the value.
  4. 4.
    To show the dynamic text, click on the
    icon, select From Variable, and choose the variable.
  5. 5.
    Click on Add Text to add new text.
To have a space between multiple texts, you must enter it manually.
Combine text

Edit multiple widgets simultaneously

We allow you to modify the properties of multiple widgets at once rather than editing each one individually. This can be a time-saving and efficient way to make bulk changes to the user interface of an app.
For example, imagine that you want to change the background color of multiple buttons in an app from blue to green. Without the ability to edit multiple widgets simultaneously, you would need to select and edit each button individually. However, with this feature, you can select all of the buttons at once and modify their fill color property.
To edit multiple widgets simultaneously, you can select all the widgets you want to modify by clicking on each one while holding down the shift key. Once you have selected all the desired widgets, you can access and modify their common properties all at once from the properties panel.
Edit multiple widgets simultaneously

Add an image from Unsplash

You can also add images directly from the Unsplash right inside the properties panel. To do so, simply click on the search icon and search and select the image. Tip: You can also choose the size of the image to add (i.e., Small, Regular, Full).
Add an image from Unsplash

Add item spacing

You can add equal space between the items of Column, Row, and ListView. To do so, head over to Properties Panel and enter the value for the Item Spacing property.
To apply the same space at the start and end of the items, enable Apply to Start & End. If you want different spacing use the Start Spacing and End Spacing properties.
Add item spacing

Primary property

When this property is true and even if the content inside the scrollable widget, such as ListView, or GridView, doesn't overflow the visible area, the user can still attempt to scroll it. The content might move slightly and then bounce back, especially noticeable on iOS with the bounce effect.
In situations where you have multiple scrollable widgets nested within each other, only one should typically be set as primary.
In most cases, the outermost scrollable widget (usually the one that takes up the most space or the full screen) is set as primary, while inner scrollables are not. For example, when you have a widget structure like this Column > ListView, you should keep the Column as primary and ListView as nonprimary.

Show error image on failure

When an image fails to load, you can display a custom image that adds a personalization touch, ensuring that even error pages can reflect your brand's unique identity. This approach provides visual feedback and helps users quickly identify issues while using your app.
To do so:
  1. 1.
    Head to Settings and Integration -> General -> App Assets and upload the Error Image.
  2. 2.
    Select the Image or CircleImage widget, move to the properties panel -> Image -> enable Show Error Image on Failure.
Upload image in App Assets
Enable 'Show Error Image on Failure'
Showing error image

Last Updated Date: September 26, 2023