Install
Works with Drupal: ^11 || ^10Using Composer to manage Drupal site dependencies
Alternative installation files
Release notes
Overview
Advanced Country Field is a comprehensive field module for Drupal that provides an enhanced country selection experience with SVG flags, filtering, search capabilities, multi-language support, and extensive customization options. This initial release (1.0.0) marks the stable debut of a production-ready module with full accessibility compliance and comprehensive test coverage.
Key Features
Multiple Widget Types
- Dropdown (Select): Standard HTML select dropdown with optional search
- Multi-select: Multiple country selection dropdown
- Radio Buttons: Single selection with accessible radio buttons
- Checkboxes: Multiple selection with checkboxes
- Automatic widget type adjustment based on field cardinality
SVG Flag Support
- Display country flags with customizable positioning (before, after, or flag-only)
- Support for popular flag libraries including
country-flag-icons - Customizable flag sizes with CSS units support (px, rem, %, vw, vh, etc.)
- Easy installation via Composer
- Support for both 3x2 and 1x1 aspect ratio flags
Multi-Language Support
- Use site language for country names
- Native country names option (e.g., "Deutschland", "España", "中国")
- Fallback to English if translation unavailable
- Comprehensive database of native country names
Country Filtering & Management
- Administrators can restrict which countries appear in dropdowns
- Custom country entries support for non-standard regions
- Real-time search functionality for quick country lookup
- Alphabetical listing with client-side filtering
Full Accessibility
- 100% WCAG 2.1 compliant
- Full keyboard navigation support
- Screen reader compatibility with ARIA labels
- High contrast mode support
- Semantic HTML and proper form labels
Developer Features
- Comprehensive Service API (
CountryDataService) - Extensible hook system for customization:
hook_advanced_country_field_countries_alter()hook_advanced_country_field_widget_options_alter()hook_advanced_country_field_validate()hook_advanced_country_field_selected()
- Event subscribers for cache management
- Twig template customization support
Value Storage Options
- Store country code only (recommended)
- Store country name only
- Store both code and name
Appearance & Customization
Widget Settings
- Show/hide country flags
- Flag position: before name, after name, or flag only
- Customizable placeholder text
- Search box overlay for long lists
- Responsive/mobile support
Display Formatter
- Display format: code, name, or both
- Flag display control
- Customizable flag dimensions
- Integration with Views
Technical Highlights
Performance
- Static caching for frequently accessed country data
- Automatic cache invalidation via event subscriber
- Optimized country data retrieval
Code Quality
- Comprehensive test coverage:
- Unit tests: 10 tests, 61 assertions
- Kernel tests: Field type, settings form, field storage, cache invalidation
- Functional tests: Module installation and basic configuration
- Drupal coding standards compliant
- Full PHPDoc documentation
Integration
- Works seamlessly with Drupal Views
- Supports all entity types (Content Types, User profiles, etc.)
- Compatible with custom modules via hooks and service API
- Field cardinality-aware widget selection
Installation
Quick Install
If you're using the Drupal Composer template:
# Install the module composer require drupal/advanced_country_field # Optional: Install flag library composer require npm-asset/country-flag-icons:^1.5 # Enable the module drush en advanced_country_field -y
For detailed installation instructions, including manual setup and configuration, see the README.md file.
Migration Notes
This is the initial release, so no migration is needed for existing sites. If you're replacing another country field module:
- Add the Advanced Country Field to your content types
- Export/import data using Drupal's standard field export tools
- Uninstall the old module once data is verified
Known Issues & Limitations
None currently reported. Please report any issues at https://www.drupal.org/project/issues/advanced_country_field
Roadmap
Future enhancements may include:
- Additional flag library options
- Enhanced search with autocomplete
- Continent/region grouping
- Country data export/import
- Migration path from Addressfield module
Credits
- Developed by the Drupal community
- Maintained by contributors
- Built following Drupal best practices and coding standards
Additional Resources
- Documentation: See README.md for comprehensive documentation
- Issue Tracker: https://www.drupal.org/project/issues/advanced_country_field
- Project Page: https://www.drupal.org/project/advanced_country_field
License
This project is licensed under the GNU General Public License, version 2 or later (GPL-2.0-or-later).
Feedback & Support
We welcome feedback, bug reports, and contributions! Please visit the project page or issue tracker to:
- Report bugs
- Suggest features
- Contribute code improvements
- Ask questions
Thank you for using Advanced Country Field!