🏗️ Architecture & Page Setup (The SPA Rule) To get the true native feel and allow the Smart History to work, your mobile app must be a Single Page Application (SPA).

Build your entire mobile app on a single Bubble page (e.g., index).

Your different "screens" should be standard Groups.

To enable the native iOS-style page transitions, assign these specific ID Attributes to your main groups at the bottom of their property panel:

Tab 1 Group ID: swiftshell-page-1

Tab 2 Group ID: swiftshell-page-2

(Repeat up to page 5)

Set your group conditionals as usual: When SwiftShell PRO's current_tab is X -> This element is visible. SwiftShell will automatically hijack the visibility and apply the smooth animation.

🪄 Setting up Bottom Sheets & App Drawers
Draw a Floating Group on your page.

In its properties, uncheck "This element is visible on page load".

Give it a unique ID Attribute (e.g., my_bottom_sheet or my_side_menu).

To open it: Use Bubble's native Show an element action, followed immediately by the SwiftShell action Open Bottom Sheet (or Open App Drawer) using that exact ID.

To close it: Let the user drag it down natively, click the blurred background, or trigger the SwiftShell action Close Bottom Sheet.

Important Cleanup: Always create a Bubble workflow using the trigger When A Bottom Sheet has finished closing -> action: Hide an element (to keep your Bubble data in sync).


📖 V2 Complete Instructions
1. General Setup & Advanced Caching

Place the SwiftShell Pro element on your page.

To use our 0ms tab switching, create 5 standard Groups on your page. Give them the HTML IDs: swiftshell-page-1 through swiftshell-page-5. The plugin will automatically cache them and switch between them instantly when users tap the bottom nav.

2. Configuring Nested Pages (Slide-in Screens)

Create a Floating Group in Bubble (this ensures it never breaks your page layout).

Set Visible on page load to YES (Crucial: This stops Bubble from deleting the HTML).

Give it an ID Attribute (e.g., my_details).

Go to the SwiftShell plugin element properties and type my_details in the Nested Pages IDs field. The plugin will magically hide it on load and slide it in only when called!

Trigger it via workflow using the Open Nested Page action.

3. Configuring Auto Dark Mode

In the plugin element properties, locate the Default Theme field. You must type exactly Light or Dark.

You do not need to set up color conditionals on your Bubble groups. Our Invert Engine will handle everything. Images and SwiftShell icons are automatically protected from inversion!

Use the Toggle Theme action on a button to let users switch themes instantly.

4. Configuring Native Onboarding

Run the Launch Onboarding action (e.g., on Page Load for new users).

Feed it a simple JSON array in the slides_json field. Example:

JSON
[
 {
   "image": "https://url.com/image1.png",
   "title": "Welcome",
   "desc": "Enjoy a native experience."
 }
]