Components and gestures
Last updated
Was this helpful?
Last updated
Was this helpful?
Mobile lists differ from web lists in a few important ways. In mobile apps, lists should never be placed within a scrolling container. Instead, a mobile list should expand to fit its content, allowing users to scroll through the screen itself rather than a confined container.
Similarly, list pagination is a web pattern that doesn't translate well to mobile and should be avoided. To support this, Vertical and Section lists are their own view types, and lists cannot be nested within each other. The only exception is with Horizontal lists, which can be placed inside a vertical or section list or on any non-list view, as they scroll in a different direction (similar to how Netflix displays content).
At this time, you cannot add multiple lists with different data sources to the same List view. However, Section lists offer a way to group list items by a specific property, essentially creating a list within a list. If having multiple lists on a single view is important for your use case, feel free to send us a feature request.
Since a List view can only accept List items as content, it provides header and footer content areas to let you add additional visual elements to your view. For instance, you might want to display a title or description above your list. These content areas can be enabled by clicking the plus buttons that appear at the top and bottom of the list element on the canvas.
Doing so adds empty content areas where you can drop any visual elements (except for lists). Keep in mind that these areas don’t have their own layout or visual properties and cannot be selected independently on the canvas or within the elements tree.
Vertical lists display a set of repeating items stacked vertically, much like a repeating group in the web editor. Each vertical list includes a list item cell template that replicates based on the data provided, ensuring a consistent layout for every item in the list.
Separators
Separator inset (px)
Separator width
Separator color
List item gap spacing
Gap spacing (px)
Reverse scroll Reverse scroll reverts the scrolling direction, which is the expected behavior in certain scenarios such as in chat conversations.
Section lists display a set of repeating items that are grouped by a specific characteristic or property. Each section list includes two cell templates: the Section Header and the List Item. The Section Header allows you to style the repeating header separately from the list items and, most importantly, set the property used to group the items. The List Item functions similarly to the Vertical List, but the individual list items will be automatically grouped based on the property defined in the Section Header's Grouping setting.
In the example above, we have taken a list of Users, each containing the field Age (number). After selecting Section List as our view type, we'll set the content type of our section list to Users and perform a search for all Users.
Next, we'll open the section header property editor to set the Grouping. Since we want to group by the user's age, we'll set the Group by to Age.
Properties
Separators
Separator inset (px)
Separator width
Separator color
List item gap spacing
Gap spacing (px)
Group by (Section header)
Used to display a list of repeating items that scrolls horizontally. The horizontal list cannot be added directly to a List view; it can only be nested within another list on a List view or added to a non-list view.
List item gap spacing
Toggles the ability to add gap spacing between list items
Item gap (px)
Defines the actual pixel value of the gap spacing between list items
List items in vertical and section lists have the option to include swipe actions, allowing users to interact with the list by swiping an item to trigger certain actions.
For example, let's say you have a task management app where users can add tasks to a list. Using swipe actions, you can allow the users to swipe left or right to complete or detele a task. This interaction provides a seamless and intuitive way for users to manage items directly within the list without adding extra elements that clutter the user interface.
Swipe actions can be customized with leading (left side) and trailing (right side) actions, and you can also set it up so that a full swipe automatically triggers the action. You can design swipe actions by selecting the relevant frame that appears on either side of the canvas, eliminating the need to hide or unhide layers. Each list item can have up to three leading swipe actions and three trailing swipe actions for a range of interactions.
One advantage of swipe actions is that they come with default animations and swipe behavior built in, making setup quick and easy. You only need to focus on customizing the look of the swipe action and deciding which workflow it triggers when swiped or tapped. To maintain a clean, consistent design, layout controls are intentionally limited to prevent swipe actions from deviating from established design best practices.
Button type - icon, label, icon and label
Icon and label fields
Icon size
Icon color
Font controls (for label)
Background style
Container alignment
Padding
Note on performance: Short lists load the entire data source at once, rather than using lazy loading. This makes them ideal for shorter lists, while longer lists may impact performance.
A Short list is a container for displaying a fixed list of data items. Unlike list views, short lists load all data at once rather than lazy-loading, which makes them best suited for small to medium lists where performance remains smooth.
Key considerations for short lists:
Supports multiple lists per view (unlike list view).
Loads all data at once.
Works well for displaying small sets of frequently used information.
A selectable list functions as an input element that allows users to select one or multiple options from a list. It is particularly useful for building filters, segmented controls, and selection forms without requiring additional custom states or workflows.
It can function in single select or multi-select mode, with additional customization options for selection limits and workflow integration. Below are the key behaviors of the selectable list.
When set to single select, the selectable list functions similarly to a radio button—only one option can be active at a time. The most recently selected item replaces any previous selection.
Users can deselect their current selection by tapping the already-selected item, returning the list to an unselected state.
When set to multi-select, users can choose multiple options instead of just one.
If no restrictions are applied, users can select as many options as they like.
If a selection limit is set (e.g., a maximum number of choices), once a user reaches the limit, all other options become disabled. The user must deselect an item before selecting a new one.
If the selectable list is marked as required, the conditional styling indicating a missing selection will only activate when the values are being saved. This is similar to how input validation works.
Once the selection meets the requirement (e.g., one item selected in single select mode, or at least two items selected in a multi-select list with a range restriction), the required styling will automatically deactivate.
The selectable list loads all items immediately, meaning it does not use lazy loading or virtualization like the vertical list.
Large data sets may impact performance, so it is important to limit the number of options when possible.
This element is not a replacement for vertical lists and should not be used when handling extensive lists of items.
Workflows can be triggered when a user interacts with a list item. When adding a workflow from the list item property editor, the "When element is clicked" workflow event is automatically pre-filled.
The following actions are available for selectable lists:
Set selectable list value: Set a selected value for the selectable list (single item or list, depending on the selection type).
Select all: Selects all the available entries in the list.
Unselect all: Deselects all selected entries.
Display list: Set a list of entries for the selectable list, formatted as a list.
Clear list: Removes all entries from the list.
Scroll to entry: Scrolls the list to specific record.
The following properties are available on selectable lists:
's list of items (if multi)
's selected item (if single)
's list of selected items (if multi)
's list of unselected items (if multi)
's minimum number of selections (if range is selected)
's maximum number of selections (if range is selected)
's number of allowed selections (if exact is selected)
Width
Height
isn’t valid
is disabled
The following conditional properties are available on selectable lists:
Minimum number of selections (number): the minimum number of selectable entries, as specified in the minimum number of selection property
Maximum number of selections (number): the maximum number of selectable entries, as specified in the maximum number of selection property
Number of selections (number): The currently number of selected entries
Sheets are similar to modals in that they provide a focused user experience, but they are best used when the immediate context of the view behind them is still relevant. For instance, Google Maps uses a sheet to display search results while allowing users to view the map in the background without switching screens. Unlike navigation elements, sheets are added directly to a view, functioning much like popups in Bubble’s web editor.
Sheets are opened using the Show element action.
Properties
Swipe to close
Toggles the ability to swipe down from the top to close the sheet. Disable this if you’d rather have the user dismiss a sheet with a button.
Block interaction behind sheet
Toggles the ability for a user to interact with the base screen when a sheet is open, similar to the behabior of popups in a web app.
Backdrop color
Sets a color that is applied over the base screen when the sheet is open, similar to the behavior of popups in a web app.
Backdrop blur
Sets a blurred overlay over the base screen when the sheet is open, similar to the behavior of popups in a web app.
Drag handle
Toggles the visibility of the horizontal drag bar at the top of a sheet. This does not impact the functionality of the sheet.
Snap points
Snap points let you define the various sizes a sheet can be. The sheet will have a default snap point, which is the size it opens to, and the user can then swipe up or down to move the sheet between the different snap points as needed. This feature is useful if the sheet contains a lot of content or if you want to allow the user to partially move the sheet out of the way to interact with the content behind it.
Floating groups are elements that can sit above other content in a view and remain fixed in place, even while the user scrolls through the rest of the page. They are especially useful for creating toolbars, banners, or any persistent elements that should always stay visible, regardless of the user's scrolling actions.
Floating groups on mobile share most of the same controls as they do on the web, with a few new options that are specific to mobile use cases, highlighted below.
Properties
Vertically float relative to
Top: Aligns to the top of the screen
Bottom: Aligns to the bottom of the screen
Both: Aligns to the center of the screen
Nothing: Defaults to the top
Horizontally float relative to
Left: Aligns to the left of the screen
Right: Aligns to the right of the screen
Center: Aligns to the center of the screen
Safe Area Behavior
Ignore: The safe area will not impact the position of the floating group on the screen
Apply to container: Position the floating group after the safe area
Apply to children: The container will ignore the safe arena but the child content in the floating group will be offset by the safe area
Move with keyboard
Checked: When selected, the floating group will shift upward to accommodate the keyboard when it appears.
Unchecked: The floating group will stay in its fixed position and will be covered by the keyboard if it appears in the same area.
Floating z-index: Determines whether the floating group should hover above or below other elements, including the view itself. Note that adding a background color to the view will block the floating group.
The Date/TimePicker is a new native mobile element specifically created for the native mobile app editor, offering an alternative to the traditional date/time picker used in the web app editor.
It automatically adapts to the device's system, displaying the iOS picker on Apple devices and the Android picker on Android devices. This behavior is enabled by default, requiring no additional configuration from your side.
The Date/TimePicker is using the native component on the device, and will not render properly on web preview.
Please use BubbleGo to test any flows involving the Date/TimePicker.
The date/time picker’s properties control two key parts:
The element placed in the view.
The native date/time picker which appears when the user clicks the element.
Picker style: Choose between:
Label/Icon: Show both a label and a customizable icon.
Label: Show just a label.
Icon placement: Choose to display the icon to the left (leading) or right (trailing) of the label.
Icon size: Set the size of the icon in pixels.
Icon color: Set the color of the icon.
Input type:
Date: Displays the date picker only. The date value will be stored in the database as the selected date + current time.
Time: Displays the time picker only. The time value will be stored in the database as the current date + selected time. To combine the date from one picker with the time from another picker, you can use the operator.
Accent color
Color picker: Sets the color of a few properties in the calendar picker. See the screenshot below.
Minimum/Maximum date: sets the minimum and maximum datetime that can be picked in the date/time picker.
The Checkbox element provides an intuitive way to manage selection states without needing complex workflows or custom states.
Here are two common use cases for the Checkbox element:
The Checkbox element can be used to filter lists, such as a list of to-do items. Instead of manually creating icons, workflows, and custom states to manage selections, you can add the Checkbox element directly to each list item. The checkbox works similarly to a button, allowing for customization of icons, labels, sizes, and colors.
It also includes built-in conditionals for the checked and unchecked states, making it simple to toggle between states by tapping. The current value of the checkbox is easily readable, so you can trigger actions based on whether it is selected or not.
Another common use case for the Checkbox element is to visually indicate task completion. For instance, when a task is marked as done, the checkbox will appear checked, and when a task is not done, it will appear unchecked. You can modify the default state of the checkbox through conditionals. For example, if a task is marked as complete in the database, the checkbox will automatically reflect that state by appearing checked. Additionally, the new “Set Checkbox” workflow action allows you to programmatically control the checkbox's state, such as when a task is marked as complete via a swipe action. This workflow not only updates the checkbox but also syncs the status with the database.
Customizable appearance: Adjust icons, labels, colors, and sizes.
Default checked/unchecked states: Built-in toggling functionality.
Conditional behavior: Reflect the current state based on conditions (e.g., task completion).
Set Checkbox workflow action: Automatically update the checkbox state via the Set checkbox action.
The Web View element allows you to display one of your app’s pages inside an element within your mobile app. You can set its responsive behavior just like any other element, ensuring it adapts well to different screen sizes.
Keep in mind that users won’t be able to navigate to other pages while using the Web View, so it’s important to design the page with all necessary content on a single page. The Web View element is limited to displaying pages from your own app, meaning external URLs cannot be used.
The Web View element currently does not work in the web preview— it only functions properly in the BubbleGo app.
The Disable Zooming property in the Webview and Scrollable View elements prevents users from using the pinch-to-zoom gesture to zoom in or out. This setting is enabled by default.
It helps improve the user experience, particularly for apps that rely heavily on webviews, where unintended zooming can cause a disruptive interface. If you want to allow zooming, you can disable this setting in the element's properties.
Mobile reusable elements are a way to create groups that can be used in more than one place in your mobile app, similar to reusable elements in a web app.
Reusable mobile elements can be of the type group or floating group, and can contain components, workflows and custom states. Each instance operates independently. This means that actions or changes within one instance of a reusable element do not impact other instances, even if they’re located on the same view.
Certain appearance properties behave differently in native mobile development compared to web development due to platform-specific rendering differences. For example, box shadows on web use CSS-based shadow settings, whereas mobile platforms rely on elevation (Android) and shadowOffset/shadowRadius (iOS). Similarly, some responsive behaviors and layout constraints may work differently due to how mobile operating systems handle UI components. Understanding these differences ensures that design choices remain visually consistent across devices.
Shadows are not yet supported in styles, but future updates will expand style settings for mobile and web elements.
Android BubbleGo currently does not display shadows due to a known issue that is being worked on.
The box shadow property allows you to add depth and visual emphasis to UI components by creating a shadow effect around them. This property functions similarly to shadows on the web but is adapted for mobile platforms to ensure consistency between iOS and Android.
iOS: Uses traditional shadow settings such as shadowOffset and shadowRadius to define the shadow’s position and blur effect.
Android: Instead of traditional shadows, Android follows Material UI 3, which uses elevation to create a shadow effect. The elevation levels are mapped to iOS shadow settings to maintain a visually consistent experience across platforms.
Bubble’s Implementation: Elevation levels on Android have been mapped to iOS shadow settings to ensure a consistent appearance across both operating systems.
Bubble provides five predefined elevation levels that translate to corresponding iOS shadow properties:
1
1dp
(0, 1)
1.5
2
3dp
(0, 3)
3
3
6dp
(0, 6)
4.5
4
8dp
(0, 8)
6
5
12dp
(0, 12)
7.5
When setting a box shadow, you are effectively selecting one of these predefined levels.
Shadows may appear slightly different between iOS and Android due to differences in how each system renders shadows.
Gestures are workflow events that trigger a workflow when a user performs a specific gesture, much like how a click triggers actions in a web app. You can assign multiple gestures to a single element. Currently, the following gestures are supported:
Similar to a ‘click’ on web. This event is triggered when a user presses and quickly releases. A tap can be canceled if a user leaves their finger pressed and removes it from the tapped area before the long press is triggered
A long press occurs when a user presses and holds their finger on the screen for a duration longer than a predefined time threshold.
