Overview

International Phone Input

A Mendix widget that provides phone number entry with integrated country code selection, flag display, and format validation. Perfect for global user forms requiring properly formatted international phone numbers.

Features

• Country code selection with dropdown menu
• International phone number format validation
• Country flag display
• Compatible with Mendix validation system
• Easy integration with existing forms

Usage

1. Download the widget from the Mendix Marketplace
2. Add the widget to your Mendix project
3. Place the widget on a page within a data view
4. Connect the widget to an attribute of type String
5. Configure the widget properties as needed

Configuration Options

• Attribute: The string attribute where the phone number will be stored
• Required: Whether the phone number is required
• Default Country: Set a default selected country
• Show Flags: Enable/disable country flag display

Documentation

PhoneNumberWithCountrySelector Widget Documentation

Typical Usage Scenario

• The PhoneNumberWithCountrySelector widget is designed for applications that need to collect international phone numbers from users.
• Perfect for customer registration forms, contact information updates, and any scenario where accurate phone number collection is essential.
• Particularly useful for businesses with global customers or operations across multiple countries.
• Solves the problem of inconsistent phone number formats and makes it easier to collect properly formatted international numbers.

Features and Limitations

Features:

• Country selection with flag display and searchable dropdown
• Supports phone numbers up to 12 digits to accommodate international formats
• Customizable phone number formatting options
• Auto-detection of user's country based on browser settings
• Clear visual feedback without unnecessary error messages for shorter numbers
• Accessible design with proper ARIA attributes for screen readers
• Combined phone number storage with country code for database efficiency
• Supports custom format patterns for special number formats

Limitations:

• Phone number validation is basic (length-based) and doesn't verify if numbers are actually valid in their respective countries
• Maximum number length is capped at 12 digits
• Custom formats must be manually defined through properties
• Does not support sending SMS verification codes directly (would require additional backend integration)

Dependencies

This widget requires:

• Mendix Studio Pro 9.0.0 or higher
• React-based page structure
• CountryData.js file must be properly integrated (included in the widget package)
• CSS file "PhoneNumberWithCountrySelector.css" must be included in your theme

Installation

1. Download the MPK file from the Mendix Marketplace
2. Import the widget into your Mendix project by right-clicking your project in the Project Explorer and selecting "Import module package"
3. Navigate to the MPK file location and select it
4. Restart Mendix Studio Pro if prompted
5. The widget will appear in the Toolbox under the "Input widgets" category

Configuration

1. Drag the PhoneNumberWithCountrySelector widget onto your page
2. Configure the following required properties:
   • Combined Phone Attribute: Database attribute to store the complete phone number with country code
   • Default Country: Set to a specific country code (e.g., "US", "DE") or "AUTO" for browser-based detection
3. Optional configurations:
   • Phone Format: Choose from "US_FORMAT", "SPACE_FORMAT", "SLASH_FORMAT", or "CUSTOM_FORMAT"
   • Use Custom Format: Set to "true" to enable custom formatting
   • Custom Format Pattern: Define a pattern using "X" as placeholders for digits (e.g., "XXX-XXX-XXXX")
4. For international compatibility, ensure you've set Maximum Length property in your database entity to at least 15 characters (to accommodate country code + phone digits)

Known Bugs

• In some browsers, the country dropdown search feature may experience minor focusing issues when clicked rapidly
• Country flags may not display properly if the server has restricted access to the flag CDN
• Auto-detection feature might default to incorrect country in rare browser configurations

Frequently Asked Questions

Q: Can I use this widget with my existing phone number database attributes?A: Yes, the widget can work with both combined storage (country code + number) and separate attributes. Configure the appropriate attribute mappings in the widget properties.

Q: How can I validate if a phone number is actually valid for a specific country?A: Additional validation would need to be implemented through custom microflows triggered on form submission.

Q: Can I customize which countries appear in the dropdown?A: Currently, the widget uses a predefined list of countries. Customization would require modifying the CountryData.js file.

Q: Why isn't the widget showing error messages for phone numbers with fewer than 10 digits?A: The widget is designed to accommodate international phone numbers, which can have varying lengths. We've intentionally removed error messages for shorter numbers to support international formats.

Q: How do I handle special phone number formats like extensions?A: Use the custom format option with an appropriate pattern that includes your extension format, such as "XXX-XXX-XXXX ext. XXXX".

Q: Can I change the flag icons used by the widget?A: Yes, modify the flagPath values in the CountryData.js file to point to your own flag assets.