Documentation Index
Fetch the complete documentation index at: https://synapsync.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Overview
NbxPhoneFieldWidget provides a user-friendly interface for selecting a country and entering a phone number, with automatic validation based on the selected country’s phone number length requirements.
Basic Usage
NbxPhoneFieldWidget(
countrySelected: null,
countryCodeInputParameters: NbxCountryPickerParameters(
isRequired: true,
inputType: NbxInputType.dropdownMenu,
decorationStyle: NbxInputDecorationStyle.outlined,
controller: countryController,
labelText: 'Country',
hintText: 'Select country',
requiredErrorMessage: 'Country is required',
),
phoneNumberInputParameters: NbxInputParameters(
isRequired: true,
inputType: NbxInputType.phone,
labelText: 'Phone Number',
hintText: 'Enter phone number',
requiredErrorMessage: 'Phone number is required',
),
modal: NbxCountryPickerModalParameters(
appBarTitle: 'Select Country',
onSelect: (country) => print('Selected: ${country.name}'),
),
)
Widget Properties
The currently selected country. Can be null if no country is selected yet.
countryCodeInputParameters
NbxCountryPickerParameters
required
Configuration for the country picker input field.
phoneNumberInputParameters
NbxInputParameters
required
Configuration for the phone number input field.
modal
NbxCountryPickerModalParameters
required
Configuration for the country picker modal/list dialog.
noCountryHelperText
String?
default:"'Select a country first'"
Helper text shown when no country is selected to indicate why the input is read-only.
NbxCountryPickerParameters
Configuration object for the country picker input.
Whether the country field is required. If true, requiredErrorMessage must be provided.
The input type. Typically NbxInputType.dropdownMenu for country pickers.
decorationStyle
NbxInputDecorationStyle
required
The visual decoration style for the input field.
controller
TextEditingController
required
Controller for the country input field.
Label text for the country field.
Placeholder text for the country field.
Error message when required country is not selected.
Widget displayed at the start of the country input.
Maximum number of lines for the country field.
NbxCountryPickerModalParameters
Configuration for the country picker modal dialog.
Required Parameters
Title displayed in the country picker modal app bar.
onSelect
void Function(Country)
required
Callback function called when a country is selected.
Appearance Options
Text color for country names in the list.
Background color for the modal app bar.
backgroundColour
Color
default:"Colors.white"
Background color for the modal content.
appBarTextColour
Color
default:"Colors.white"
Text color for the app bar title.
backIconColour
Color
default:"Colors.white"
Color for the back button icon.
dividerColour
Color
default:"Colors.black12"
Color for dividers between countries.
Typography Options
appBarFontStyle
FontStyle
default:"FontStyle.normal"
Font style for the app bar title.
countryFontStyle
FontStyle
default:"FontStyle.normal"
Font style for country names.
Font size for the app bar title.
Font size for country names.
appBarFontWeight
FontWeight
default:"FontWeight.bold"
Font weight for the app bar title.
countryFontWeight
FontWeight?
default:"FontWeight.bold"
Font weight for country names.
Search Bar Options
searchBarBackgroundColor
Color
default:"Colors.white"
Background color for the search bar.
Border color for the search bar.
Text color for search input.
Hint text color for search input.
searchBarOuterBackgroundColor
Color
default:"Colors.white"
Outer background color for the search bar container.
Border width for the search bar.
Whether to autofocus the search bar when modal opens.
searchBarIcon
IconData
default:"Icons.search"
Icon displayed in the search bar.
Whether to show the search bar in the modal.
Display Options
Whether to center-align the app bar title.
Whether to display phone codes alongside country names.
backIcon
IconData
default:"Icons.arrow_back"
Icon for the back button in the app bar.
listType
ListType
default:"ListType.list"
Type of list display for countries.
countryTheme
CountryThemeData
default:"CountryThemeData(appBarBorderRadius: 10)"
Theme configuration for the country picker.
Optional list of countries to display. If null, all countries are shown.
Country Object
The Country object contains information about the selected country:
name - Country namephoneCode - International dialing codecountryCode - ISO country codeminLength - Minimum phone number lengthmaxLength - Maximum phone number length
Behavior
Automatic Validation
The phone number input automatically validates based on the selected country:
- Minimum length validation using
country.minLength
- Maximum length validation using
country.maxLength
- The
maxLength property is applied to the text field
Read-Only State
The phone number input becomes read-only when no country is selected, preventing users from entering a phone number without context.
State Management
When a country is selected:
- The phone number input is cleared
- The original
onSelect callback is called
- The input becomes enabled for phone number entry
Examples
Basic Phone Field
final countryController = TextEditingController();
final phoneController = TextEditingController();
Country? selectedCountry;
NbxPhoneFieldWidget(
countrySelected: selectedCountry,
countryCodeInputParameters: NbxCountryPickerParameters(
isRequired: true,
inputType: NbxInputType.dropdownMenu,
decorationStyle: NbxInputDecorationStyle.outlined,
controller: countryController,
labelText: 'Country',
requiredErrorMessage: 'Please select a country',
),
phoneNumberInputParameters: NbxInputParameters(
isRequired: true,
inputType: NbxInputType.phone,
controller: phoneController,
labelText: 'Phone Number',
hintText: 'Enter phone number',
requiredErrorMessage: 'Phone number is required',
),
modal: NbxCountryPickerModalParameters(
appBarTitle: 'Select Country',
onSelect: (country) {
setState(() {
selectedCountry = country;
countryController.text = country.name;
});
},
),
)
With Custom Styling
NbxPhoneFieldWidget(
countrySelected: selectedCountry,
countryCodeInputParameters: NbxCountryPickerParameters(
isRequired: true,
inputType: NbxInputType.dropdownMenu,
decorationStyle: NbxInputDecorationStyle.outlined,
controller: countryController,
labelText: 'Country',
prefixIcon: Icon(Icons.flag),
requiredErrorMessage: 'Country required',
),
phoneNumberInputParameters: NbxInputParameters(
isRequired: true,
inputType: NbxInputType.phone,
controller: phoneController,
labelText: 'Mobile Number',
prefixIcon: Icon(Icons.phone),
requiredErrorMessage: 'Phone required',
),
modal: NbxCountryPickerModalParameters(
appBarTitle: 'Choose Your Country',
showPhoneCode: true,
searchBarAutofocus: true,
appBarBackgroundColour: Colors.blue,
countryTextColour: Colors.black87,
onSelect: (country) {
setState(() {
selectedCountry = country;
countryController.text = '${country.name} (+${country.phoneCode})';
});
},
),
noCountryHelperText: 'Please select a country first',
)
With Limited Countries
NbxPhoneFieldWidget(
countrySelected: selectedCountry,
countryCodeInputParameters: NbxCountryPickerParameters(
isRequired: true,
inputType: NbxInputType.dropdownMenu,
decorationStyle: NbxInputDecorationStyle.outlined,
controller: countryController,
labelText: 'Country',
requiredErrorMessage: 'Country is required',
),
phoneNumberInputParameters: NbxInputParameters(
isRequired: true,
inputType: NbxInputType.phone,
controller: phoneController,
labelText: 'Phone',
requiredErrorMessage: 'Phone is required',
),
modal: NbxCountryPickerModalParameters(
appBarTitle: 'Select Country',
countries: [
// Provide specific countries only
usCountry,
ukCountry,
canadaCountry,
],
onSelect: (country) {
setState(() {
selectedCountry = country;
countryController.text = country.name;
});
},
),
)
See Also