Install

Works with Drupal: ^11 || ^10

Using Composer to manage Drupal site dependencies

Alternative installation files

Download tar.gz 46.72 KB
MD5: 5fca7fe30a93598d0233b9b4dbd92886
SHA-1: d605e2fe8b26be586290e531f3b62039f580c00e
SHA-256: 939d213056a16c2f6a9d89a0c069a0a248489b5f2f3566186c6b5a021a4fea82
Download zip 67.5 KB
MD5: 6c1f93677325663d51ac5b0e2a63f3cb
SHA-1: 3a8c1069d4d519e59177e09794f3ffd7ffc8bbee
SHA-256: c7462d716808fef3d9885266bda7d1f5708d0a24a6719ac1f1718718e4b9d283

Release notes

Release Notes - Advanced Country Field 1.0.0

Release Date: January 17, 2025

Drupal Versions: 10.x, 11.x

PHP Requirement: 8.1 or higher

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:

  1. Add the Advanced Country Field to your content types
  2. Export/import data using Drupal's standard field export tools
  3. 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

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!

Created by: ilyaselhaddaji
Created on: 2 Nov 2025 at 01:44 UTC
Last updated: 2 Nov 2025 at 01:44 UTC
New features
Unsupported

Other releases