Components and gestures

Components

Lists

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).

Multiple lists

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.

List Header / Footer content areas

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.

You can add visual elements on top of your list view...

... or underneath it.

Vertical list

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.

Properties

• 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 list

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 this example, we have taken a list of users and created sections based on their age (a numerical value).

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.

Any property within the data type can be used for grouping, except for fields that reference another data type.

Properties

• Separators

• Separator inset (px)

• Separator width

• Separator color

• List item gap spacing

• Gap spacing (px)

• Group by (Section header)

Horizontal List

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.

Properties

• 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 item swipe actions

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.

List item swipe actions lets users interact with items in a list without adding additional elements to 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.

Properties

• Button type - icon, label, icon and label

• Icon and label fields

• Icon size

• Icon color

• Font controls (for label)

• Background style

• Container alignment

• Padding

Short List

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.

Selectable lists

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.

Single select behavior

• 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.

Multi-select behavior

• 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.

Validation and required lists

• 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.

Performance considerations

• 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 and actions

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.

Properties

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

Conditional properties

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

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 Group

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 will position themselves just below the top app bar when aligned to the top or just above the tab bar when aligned to the bottom, if either of these elements are present on the view.

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.

Date/TimePicker

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.

Appearance

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.

Element properties

• 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.

Native date/time picker properties

• 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 accent color property lets you specify a color for specific parts of the native date/time picker.

Checkbox

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:

Filtering to-dos

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.

Managing Task Status

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.

Key Features:

• 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.

WebView

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.

Disable zoom

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

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.

General appearance properties

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.

Box shadow property (elevation on Android)

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.

How Box Shadow Works on Mobile

• 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.

Box Shadow Levels

Bubble provides five predefined elevation levels that translate to corresponding iOS shadow properties:

Level	Elevation (Android)	iOS Shadow Offset	iOS Shadow Radius
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.

Platform-Specific Differences

Shadows may appear slightly different between iOS and Android due to differences in how each system renders shadows.

Gestures

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:

Tap

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

Long Press

A long press occurs when a user presses and holds their finger on the screen for a duration longer than a predefined time threshold.