NOTE: Google Maps browser keys are visible in client-side apps by design. For security, restrict your key in Google Cloud by allowed website referrers and allowed APIs. This prevents the key from being used outside your Bubble app domains.

SETUP

1. In Google Cloud Console, enable these APIs for your project:

- Maps JavaScript API
- Places API
- Places API (New)
- Geocoding API

2. Create a Google Maps browser API key.

3. In Google Cloud, restrict the key by website referrer when you are ready for production. Example referrers:

https://yourdomain.com/*
https://www.yourdomain.com/*
https://*.bubbleapps.io/*

4. In your Bubble app, go to Plugins > AddressFlow and paste your Google API key into:

google_maps_api_key

If you see a development key field, paste the same key there while testing.


ELEMENT SETUP

Add the AddressFlow element to your page.

Recommended Bubble element layout:

Width: 400px
Height: 56px

Recommended responsive layout:

Width: 100% of the available container when used in forms
Minimum width: 240px
Height: 56px

Recommended plugin defaults:

placeholder: Search address
country_codes: ca
radius_unit: km
strict_radius_filter: yes
language: en
min_chars: 3
debounce_ms: 250
show_powered_by_google: yes
input_height: 48
dropdown_max_height: 300
border_radius: 8
border_color: #D7DEE8
focus_color: #1F7AEC
shadow_color: rgba(16,24,40,.16)
background_color: #FFFFFF
text_color: #17202A
placeholder_color: #7A8798
result_hover_color: #F6F9FD
icon_color: #1F7AEC
show_location_icon: yes
font_size: 16
result_title_font_size: 14
result_subtitle_font_size: 12
result_title_weight: 650
result_subtitle_weight: 400

Leave element_width and element_height blank unless you want to override Bubble’s layout sizing. When blank, AddressFlow uses Bubble’s responsive layout width and height.


COUNTRY FILTERING

Use country_codes to limit results to one or more countries.

Examples:

ca
us
ca,us
gb

Use lowercase two-letter country codes for best results.


CENTER POINT AND RADIUS SEARCH

AddressFlow can bias or validate results around a center point.

Option 1: Use a center address

center_address: Toronto, Ontario
radius: 25
radius_unit: km
strict_radius_filter: yes

Option 2: Use latitude and longitude

center_latitude: 43.6532
center_longitude: -79.3832
radius: 25
radius_unit: km
strict_radius_filter: yes

If center_latitude and center_longitude are provided, they are used instead of center_address.

If strict_radius_filter is yes, an address outside the selected radius is blocked after selection and the outside_radius_selected event is triggered.


WORKFLOWS

Use the event:

When AddressFlow address is selected

Then save any exposed states you need, such as:

selected_full_address
selected_latitude
selected_longitude
selected_city
selected_region
selected_country
selected_postcode
selected_place_id
selected_distance_from_center
selected_is_inside_radius

Example database mapping:

Address = AddressFlow's selected_full_address
Latitude = AddressFlow's selected_latitude
Longitude = AddressFlow's selected_longitude
City = AddressFlow's selected_city
Region = AddressFlow's selected_region
Country = AddressFlow's selected_country
Postal code = AddressFlow's selected_postcode


EVENTS

address_selected:
Triggered when the user selects a valid address.

search_started:
Triggered when AddressFlow starts searching Google Places.

search_finished:
Triggered when Google Places returns search results.

search_error:
Triggered if Google or the plugin returns an error.

center_resolved:
Triggered when center_address is converted into latitude and longitude.

outside_radius_selected:
Triggered when a user selects an address outside the configured radius.


EXPOSED STATES

query:
Current text typed into the search box.

is_loading:
Yes while searching or loading selected address details.

error_message:
Latest error message, useful for debugging.

results_json:
Raw result data from the latest search or selected address.

selected_full_address:
The full formatted address selected by the user.

selected_name:
The main name/title of the selected result.

selected_place_id:
Google Place ID.

selected_latitude:
Latitude of the selected address.

selected_longitude:
Longitude of the selected address.

selected_city:
City/locality from the selected address.

selected_region:
State, province, or region from the selected address.

selected_country:
Country from the selected address.

selected_postcode:
Postal or ZIP code from the selected address.

selected_distance_from_center:
Distance in kilometers from the configured center point.

selected_is_inside_radius:
Yes if the selected address is inside the configured radius, or if no radius is set.

center_latitude_resolved:
Latitude of the resolved center point.

center_longitude_resolved:
Longitude of the resolved center point.


STYLING

AddressFlow includes styling fields for:

- Input height
- Dropdown max height
- Border radius
- Border color
- Focus color
- Dropdown shadow color
- Background color
- Text color
- Placeholder color
- Result hover color
- Location icon color
- Custom SVG location icon
- Font size
- Result title size
- Result subtitle size
- Font weights

For mobile, keep font_size at 16 or higher. Mobile browsers may zoom into inputs when the font size is smaller than 16px.

You may leave custom_location_icon_svg blank to use the default location pin. If using a custom icon, paste an inline SVG. Icons that use currentColor will automatically follow icon_color.


WHY ADDRESSFLOW IS BETTER

AddressFlow is built for real Bubble apps, not just simple demos.

It provides:

- Clean Google Places autocomplete
- Country filtering
- Optional center address or center coordinates
- Radius search and strict radius validation
- Mobile-friendly behavior
- No clipped dropdown inside Bubble containers
- Exposed address states for workflows
- Useful events for search, selection, errors, and radius validation
- Custom styling controls
- Optional custom location icon
- Google attribution support
- Sensible defaults that work well out of the box

The plugin is designed to be flexible without forcing builders into one layout. It works with Bubble’s responsive layout by default, while still allowing optional visual width and height overrides if needed.


TROUBLESHOOTING

If no results appear, check:

1. The Google API key is added in the plugin settings.
2. Maps JavaScript API is enabled.
3. Places API is enabled.
4. Places API (New) is enabled.
5. Geocoding API is enabled.
6. The API key website referrers include your Bubble preview/live domain.
7. API restrictions include the required Google APIs.

If mobile zooms into the input, set:

font_size: 16

If the dropdown is too tall or too short, adjust:

dropdown_max_height

If the dropdown appears outside the expected area, make sure the page/container is not applying unusual transforms or overflow behavior.


SUPPORT

For questions or support, contact:

bassim3qazi@gmail.com