Widget Commonalities
While working with widgets, you may find some features or properties that are common across various widgets. This page will guide you on how to implement these common functionalities or modify properties that are uniformly applicable to multiple widgets.
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
See how to get style from default widgets.
Visibility
Conditional
See how to show or hide widgets.
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:
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:
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.
Furthermore, you can utilize these breakpoint values throughout your app to tweak the widget properties based on the screen size. For example, you might set different width and height values for a Container widget depending on whether the screen size matches with small, medium, or large.
You can access the breakpoint values via the Set from Variable menu. Here's an example of setting the Container width based on the screen size.
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 and 1. e.g., 0 means full transparency, one is opaque, and 0.5 is half transparent.
Padding & Alignment
Add padding
Padding is the empty space around the outer side of the widget.
To add a padding:
Select the widget from the widget tree or from the canvas area.
Move to the properties panel and navigate to the Padding & Alignment section.
Enter values for Left (L), Top (T), Right (R), Bottom (B).
To apply the same padding on all sides, switch to the Uniform Padding option. You can then adjust the padding by either moving the slider or entering the desired value directly.
Use the refresh icon button to reset all values.
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:
Select the widget, and head over to Properties Panel > Padding & Alignment section.
Use the alignment box to align the widget at a fixed position or directly enter a value in the Horizontal and Vertical input box.
If you prefer watching a video tutorial, here is the guide for you:
Testing
This property 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
To change the size, navigate to the Width and Height properties, and then you have three choices for setting the size:
For a specific size, choose PX and type in the size you want.
For a size based on the screen, choose % and type in the percentage.
To make the widget fill the whole screen width or height, click on the infinity symbol (∞).
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:
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:
Select the widget and then select the sizing option: Flexible or Expanded.
Try adding Flex value, such as Widget A Flex = 1 and Widget B Flex = 2.
In the visual above, when setting the Flexible option, see how the widgets are first displayed with specified height and then stay in propertion when height is increased.
If you prefer watching a video tutorial, here is the guide for you:
Change color
To change color for any widget property:
Navigate to a widget property that allows you to set a color.
Click on the currently selected color to either pick a new color or enter the Hex Code directly.
By default, theme colors are displayed. Simply click on a color to apply it.
For a custom color, switch to the Custom Color tab, select your desired color, and then click Use Color.
You can also set a color from variable.
Opening Drawer from an AppBar
To access the Drawer without an AppBar widget, users need to swipe on the page. However, this might be confusing as there's no indication of the Drawer's existence. Adding an AppBar widget resolves this by automatically displaying a menu icon (three-line icon), signaling the presence of the Drawer. This enhances user awareness and interaction with the Drawer feature.
Styling text
To customize your text, you can use predefined styles or define your own using these properties:
Theme Text Style: Use this to apply a consistent style based on your app's theme.
Font Family: Use this to set font that fits your design.
Font Weight: Use this to adjust the thickness of the text from light to bold.
Styling: Use this to apply styles like italic, underline, or strikthrough.
Font Size: Use this to set the size of your text.
Text Color: Use this to set the color for your text.
Line Height: Use this to set the height of the text (e.g. a value of 1.5 would make the line height 50% larger than the font size.)
Letter Spacing: Using this you can control the space between individual letters.
Text Align: Use this to set the text alignment to left, center, right or justify.
For consistency, we recommend creating your custom text styles before starting your project.
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, move to the properties panel > Text Properties > enter the Max Lines value.
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:
Move to the properties panel > Image > Image Type dropdown. Click on Network (inside the dropdown) and select Asset.
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:
Select the widget from the widget tree or from the canvas area.
Move to the Property Editor (on the right side of your screen) and scroll down to the Image section.
Find the Image Type dropdown. Click on Network (inside the dropdown) and select Asset.
Click on No asset select (inside the dropdown) and choose the image.
Showing Image on fullscreen
To accommodate different device sizes where the image might appear small, consider making the image expandable. This allows users to view it in full screen and zoom or pan for better detail and interaction.
To make the image expandable, move to the properties panel > Image > switch on the Make Expandable toggle.
Doing so will add an Expand Image Action on the Image.
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:
To set dark mode version of your image:
Select the Image widget > move to the Properties Panel > set Image Type to Asset.
Enable Set Dark Mode.
Select the Light Mode Asset and Dark Mode Asset. You can upload images directly from here as well.
Customizing Icon
To customize icon for any widget:
Move to the Properties Panel > Icon > Click on the default icon > search and select the icon.
To change its size, use the Icon Size property.
To change its color, use the Icon Color property.
Styling ListTile
Changing background color
To change the background color, move to the Properties Panel > Style Properties > set the Color.
Add content padding
Content Padding adds space between the item content and the border of your ListTile.
To add the content padding:
Head over to the Properties Panel > Style Properties > Content Padding.
Enter values for Left (L), Top (T), Right (R), Bottom (B).
To apply the same padding on all sides, switch to the Uniform Padding option. You can then adjust the padding by either moving the slider or entering the desired value directly.
Use the refresh icon button to reset all values.
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, move to the Properties Panel > Style Properties > switch on the Dense toggle.
Customizing ListTile title
See how you can style a ListTile title.
Customizing ListTile subtitle
See how you can style a ListTile subtitle.
Add ListTile leading icon
The Leading Icon appears at the start (left side) of the ListTile. To add a leading icon, move to the properties panel > Leading Icon Properties and set the icon as per the instructions here.
Adding border
To add a border to any widget:
Find the Border Color property and change the color using the instructions here.
To create the rounded border, use the Border Radius property.
Enter values for TL (Top left), TR (top right), BL (bottom left), and BR (bottom right).
To apply the same radius on all sides, switch to the Uniform Radius option. You can then adjust the radius by either moving the slider or entering the desired value directly.
Use the refresh icon button to reset all values.
To increase the border thickness, use the Border Width property.
Enable pull to refresh
If you've enabled the Single Time Query for a Backend Query in a scrollable widget, it won't refresh the list when items are updated in the backend. To address this, add a pull-to-refresh feature.
This user interface pattern allows users to manually refresh content by pulling down the content area, such as a list. When pulled down sufficiently and released, the app will refresh, fetching the latest data or updates.
To enable pull to refresh:
Select your scrollable widget, such as ListView, GridView, or StaggeredView.
Move to the properties panel and select the Backend Query.
Open the already added query (e.g., Query collection or API call) and make sure the Single Time Query is enabled.
Switch on the Enable Pull to Refresh toggle. This will automatically add the Refresh Database Request action on a pull to refresh gesture.
Also, see how to customize the appearance of the pull to refresh style.
Setting color from variable
You may want to apply dynamic colors to widget properties like Container backgrounds or Text colors, which can be achieved by assigning colors from a variable. For instance, you can display temperature color dynamically based on an app state variable, data from a Firestore document, responses from API calls, or other similar sources.
To set a color from a variable:
Navigate to a widget property that allows you to set a color.
From the Set from Variable menu, you can select the source of your color. Below is an example of setting color from an app state 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.
To simplify, we've used the Dropdown widget as an example. However, the same instructions apply to other Form widgets as well.
To do so:
Select the widget.
Select Actions from the properties panel, and click + Add Action.
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.
Now you can add any action here.
Here is an example showing the snackbar message when the Dropdown selection changes.
Copy variable
If you have a complex variable value (e.g., using Conditional Logic) and want to use the same logic in another variable value, you can do so by copying a variable.
To copy-paste a variable:
Open the Set from Variable menu and select the Variable Options (three dots) icon.
Select the Copy Variable.
Move to the place where you want to paste the variable, and open the Set from Variable menu.
Click on the Paste Variable icon.
Click Confirm.
Combine text
Using this, you can combine multiple text segments into one. For instance, in the phrase 'you have 3 notifications,' 'you have' and 'notifications' are static texts, while '3' is a dynamic value sourced from a variable.
To display combined text:
Select the widget property that can show a text (e.g., Text, TextField).
Open Set from Variable menu and use Combine Text option.
To have a space between multiple texts, you must enter it manually.
Edit multiple widgets simultaneously
We also allow you to modify the properties of multiple widgets at once. 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.
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 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.
For GridView and StaggeredView, you can directly access the Start Spacing and End Spacing properties.
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:
Head to Settings and Integration > General > App Assets and upload the Error Image.
Select the Image or CircleImage widget, move to the properties panel > Image > enable Show Error Image on Failure.
UI builder display value
For widgets like Text and RichText, when their content is coming from a variable, you have the option to set a placeholder value that will be displayed only in the app builder. Keep in mind that this display value is solely for visualization purposes within the canvas and will be replaced with the actual variable value when the app is running.
This is helpful in assessing spacing and alignment without the need to remove variable bindings.
Last Updated Date: April 5, 2024
Last updated
