GCS Studios
Every Country, With Flags
A country selector with SVG flags and dial codes, in the language of the visitor's browser, or in a locale you pin yourself.
Why use this?
Built for what Bubble does not cover.
Bubble's native phone field is not a dedicated input. It is one type of a generic input that also does text, number, password, email and others. It accepts a phone number and can check a basic format, but it has no country selector, no flags, no formatting while the person types, and no way to tell a valid São Paulo mobile from eleven digits that merely look like one. Whatever is typed is what your database gets, in whatever shape the person chose to type it.
Key features 6
Searchable Country List
Find a country by name, by ISO code or by dial code, with your own message when nothing matches.
Validation Per Country
A number is checked against the rules of the country it belongs to, not against a generic pattern.
The Number, In Every Shape
E.164 for your database, the national form for your screens, and the country, area and local parts on their own.
Complete Styling Control
The field, the selector, the floating panel, its search box and each country row are all yours to style.
Accessible Experience
Fully operable from the keyboard and announced to screen readers, with motion preferences respected.
In detail
International by Design
- Country selector with SVG flags and dial codes
- Search the country list by name, ISO code or dial code
- Your own message when the search matches no country
- Formatting as you type for every country
- Per-country number validation
- Pasting an international number switches the country automatically
- Allowed, blocked and preferred countries
Fully Customizable
- 50+ properties for complete visual and behavioral control
- National or international display format
- Floating country list with position, animation types, and modern glass effects
- Country search with its own colors, height, search icon and clear icon
- Fully customizable country states: available, hovered and selected
- Choose how many countries show before the list scrolls, the scrollbar style and faded edges while there is more to scroll
- Seamless integration with native Bubble styles while preserving a consistent appearance across browsers and matching your app design
Smooth User Experience
- Keyboard navigation in the country list with arrows, Enter, and Escape
- Country names in the visitor’s language, or pinned to the locale you choose
- Handles required and invalid states with customizable styling that integrates with Bubble styles
- Screen reader ready, with an accessible label and description, and reduced motion support
Workflow Friendly
- Exposed states for the number in E.164, its national formatting, and the country, dial, area and local parts on their own
- Initial value available to your workflows even while the element is hidden
- Focus action that can be triggered from anywhere for full workflow control
- Reset action with flexible behavior that integrates with native Bubble actions or custom workflows
- Set value action that can be triggered from anywhere, with control over how it behaves when the input is disabled
- Value changed and country changed events for seamless Bubble integration
- Powered by libphonenumber-js for formatting and validation
Reliable & Production-Ready
- Built with lightweight CSS and JavaScript for fast, reliable performance
- Country data pinned to one library version, so an update never changes behavior without notice
- Designed around practical use cases and real Bubble development needs
- Tested in real-world applications before being released publicly
- Created to extend Bubble with functionality and customization beyond what native Bubble elements typically offer
How to use 3
-
01
Insert the element on the page
Place the plugin element wherever you need it.
-
02
Configure the properties
Adjust the settings to match your use case, including the default country, the allowed and preferred countries, and the validation.
-
03
Connect to your workflows
Use the value changed and country changed events to capture the confirmed number and read the exposed states to use them anywhere in your app.
INPUT 12
The number is published in several shapes at once, and they are not interchangeable. Store value, which is E.164 and unambiguous anywhere in the world; show value (formatted), which is how the number is written inside its own country. area code and local number exist for forms that keep the parts in separate columns.
General
Input placeholder
Text displayed in the input while it has no value.
Input placeholder color
Color of the placeholder text.
Divider line color
Color of the line between the country selector and the input. Leave it empty to follow the element's native border color, or a light grey when the element has no border.
Display format
How the number is formatted inside the input.
This changes only what the person sees while typing. The `value` state is always E.164, whichever format you pick here, so your database is not affected by this choice.
Validate number?
Checks whether the number is valid for the selected country.
Country selector
Locale
BCP 47 locale that defines the language of the country names (for example en-US or pt-BR). When empty or invalid, uses the browser locale.
Display flag?
Shows the country flag in the selector.
Display dial code?
Shows the dial code (+55) next to the flag.
Allowed countries (press Enter between each code)
ISO codes available in the selector. Leave empty to list all countries. One code per line, and it accepts a dynamic list, so the countries can come from your data.
One ISO code per line, pressing Enter between them. A default value whose country is not on this list is ignored, and the field opens on the default country instead.
Blocked countries (press Enter between each code)
ISO codes removed from the selector. A blocked country is removed even when it is listed as allowed. Leave empty to block none. One code per line, and it accepts a dynamic list, so the countries can come from your data.
Preferred countries (press Enter between each code)
ISO codes shown at the top of the list. One code per line, and it accepts a dynamic list, so the countries can come from your data.
Default country
ISO 3166 code of the country selected on load (US, BR, PT...).
DEFAULT DATA 1
Default value
Phone number applied on load and on reset, in international format (+5511912345678).
FLOATING PANEL 10
General
Max visible options
Sets the maximum number of visible countries before scrolling. Accepts values between 1 and 30.
The height is worked out from this count and the font size you set, so the panel shows this many countries whatever the typography. The rest scrolls.
Panel position
Preferred or forced opening direction of the floating panel relative to the input.
Animation type
Opening animation of the floating panel.
Appearance
Panel bg color
Background color of the floating panel.
Panel border color
Sets the border color of the floating panel.
Glass effect
Intensity of the glassmorphism effect on the floating panel.
Scrollbar
Scrollbar style
Look of the scrollbar in the panel lists: hidden (the list still scrolls), minimal (a handle only) or arrows (a handle with an arrow at each end), each in thin or regular width. Firefox shows its own scrollbar for arrows.
Fade list edges?
Fades the top and bottom edges of the panel lists while there are more items to scroll to on that side.
Empty state
Empty state label
Message displayed inside the panel when there are no options to show.
Empty state font color
Font color of the empty state message.
SEARCHBOX 15
Search input
Enable search input?
Shows a search input in the country list.
The search matches a country by name in the visitor's language, by ISO code, and by dial code, so typing `br`, `BR` or `+55` all find Brazil.
Search input placeholder
Placeholder of the country search input.
Search results label
Text read by screen readers after each country search. {count} is replaced with the number of countries found.
Search input height
Height of the search field, in pixels. Leave it empty to follow the element's height.
Search input bg color
Sets the background color of the search input.
Search input border color
Sets the border color of the search input.
Search input border color (focused)
Sets the border color of the search input when focused.
Search input font color
Sets the color of the text typed in the search input. It is optional, if not set falls back to the native font color set in the main input.
Optional. Left empty, the text typed in the search follows the font color of the main input, so the panel matches the field without a second setting.
Search input placeholder color
Sets the font color of the search input placeholder.
Clear search input on close?
Enables automatic clearing of the search text when the panel closes. Disabled keeps the typed search for the next time the panel opens.
Search icon
Display search icon?
Displays the search icon inside the search input.
Search icon class
Sets the icon displayed next to the search input.
Search icon color
Sets the color of the search icon.
Clear icon
Clear icon class
Sets the icon used to clear the search input. It appears only while there is text typed.
Clear icon color
Sets the color of the clear icon.
LIST OF OPTIONS 9
Available options
Option bg color (available)
Sets the background color of countries in their default state. Empty leaves them transparent.
Optional, and empty on purpose: the list is a column of flags, and a background behind every row competes with them. Set it only if you want the rows banded.
Option border color (available)
Sets the border color of countries in their default state. Empty leaves them without a visible border.
Option font color (available)
Sets the font color of countries in their default state. Empty follows the element font color.
Hovered options
Option bg color (hovered)
Country background color on hover.
Option border color (hovered)
Sets the border color of countries when hovered.
Option font color (hovered)
Country font color on hover. Empty keeps the element font color.
Selected options
Option bg color (selected)
Country background color when selected.
Option border color (selected)
Sets the border color of countries when selected.
Option font color (selected)
Font color of the selected country.
INPUT BEHAVIOR 9
Disabled state
This input is disabled?
Disables the component, preventing any interaction.
Input bg color (disabled)
Input background color when disabled.
Input border color (disabled)
Input border color when disabled.
Input font color (disabled)
Input font color when disabled.
Required state
This input is required?
Marks the field as required and enables input validation.
Input bg color (invalid)
Input background color when invalid.
Input border color (invalid)
Input border color when invalid.
Focused state
Input bg color (focused)
Input background color when focused.
Input border color (focused)
Input border color when focused.
ACCESSIBILITY 2
Accessible label
Name read by screen readers. When empty, uses the placeholder or the visible label.
Accessible description
Hint read by screen readers after the name. Empty for none.
States 11
Values the element exposes for the rest of the page to read.
An optional input can still be invalid: once there is a number, it has to be valid for the selected country, unless Validate number? is unchecked.
value
Number in international E.164 format (+5511912345678). Empty when the input is empty.
value (formatted)
Number grouped the way it is written in the selected country ((11) 91234-5678). Empty when the input is empty.
country code
ISO code of the selected country.
dial code
Dial code of the selected country (+55).
area code
Area code of the number, in the countries that use one (the DDD in Brazil). Empty where the country has no area code, such as Germany, France and Spain.
local number
Number without the dial code and without the area code. Where the country has no area code, it is the whole national number.
active locale
The locale that actually applied: the Locale field when it is valid, or the visitor's browser language when the field is empty or its form is not recognised.
is clickable
True when the component is not disabled.
is required
True when the input is marked as required.
is valid
True when the value is accepted. False when it is required and empty, or Validate number? is checked and the number is not valid for the selected country. It updates on every change, so a workflow can rely on it; the invalid style only shows after the person leaves the field or closes the panel, or when a workflow sets the value.
is focused
True while the input has focus.
Events 2
Where a workflow can start.
value changed
Triggered when the number is confirmed with a different value: leaving the input, pressing Enter, changing the country or resetting.
country changed
Triggered when a different country is selected.
Actions 3
What a workflow can tell the element to do.
Reset no params
Restores the default number and country, or clears the input.
Focus no params
Focuses the phone input.
Set value 2 params
Writes a phone number into the field from a workflow. A number starting with + carries its own country; without it, the number is read in the default country.
Apply even when disabled?
Yes applies the value even while the element is disabled. No makes the action do nothing in that state.
Value
The value to write into the field. It goes through the same treatment as a value typed by the user. An empty value clears the field, keeping the selected country.
FAQ 7
What exactly do I get back when someone types a number?
Six separate states. `value` is the number in international E.164 format (`+5543991234567`), which is what belongs in your database and what an SMS gateway expects. `value (formatted)` is the same number grouped the way it is written inside the country (`(43) 99123-4567`). `country code` is the ISO code (`BR`), `dial code` is `+55`, `area code` is the DDD (`43`) and `local number` is what is left (`991234567`).
Why is the area code empty for some countries?
Because those countries do not have one. Brazil, the United States, Canada, Chile and Russia use an area code; Germany, France, Spain and the United Kingdom do not, and the digits that look like one there are a mobile or carrier prefix. The plugin publishes an area code only where the country really has one, and leaves the state empty everywhere else, rather than handing you a number that looks like a region and is not.
Does it validate the number, or just the format?
It validates against the rules of the selected country, using libphonenumber, the same library behind Google's phone number handling. A mobile number with the wrong number of digits for its area fails even though it looks plausible. You can turn validation off with Validate number? if you only want formatting.
Can I limit which countries appear?
Yes. Allowed countries restricts the list to the ISO codes you list, one per line. Blocked countries removes the ones you list and keeps the rest. Preferred countries pins the ones you list to the top, above a divider, without removing the rest. Leave all three empty and every country is offered.
What happens if someone pastes an international number?
The selector follows it. Pasting a number that starts with `+` switches the country to the one the number belongs to, as long as that country is allowed, and the digits are reformatted for it. The same applies to the Set value action.
Where does the country data come from, and does it slow the page down?
From libphonenumber-js, pinned to one version and loaded once per page from a CDN, around 60 KB compressed. Flags are SVG files fetched one at a time, only as they appear on screen. Until the library arrives the field still accepts digits, simply without formatting, so nothing blocks typing.
Can I set or clear the number from a workflow?
Yes. The Set value action writes a number from anywhere in your app, with control over whether it applies while the input is disabled; Reset returns the field to its default value and country; and Focus puts the cursor in it. Two events let you react: one when the number changes and one when the country changes.
NWD UI - Input
This plugin is maintained by GCS Studios and is part of the NWD UI - Input family, form controls built from scratch for Bubble, inspired by a personal component library originally built for React. Each one is carefully designed and tested in real applications before release, for the level of control, polish and reliability that native Bubble inputs often do not provide. See more plugins on the GCS Studios contributor page.
Each control here is drawn by the plugin instead of being restyled from a native one, so they match each other across the library and keep the same shape in every browser.