Flag Icon Css Laravel Package

Getting Started

Minimal Steps

1. Installation:

   npm install flag-icons
   

   or via CDN:

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/lipis/[email protected]/css/flag-icons.min.css" />
   

2. First Use Case: Display a flag for Greece inline with text:

   <span class="fi fi-gr"></span> <!-- Default flag -->
   <span class="fi fi-gr fis"></span> <!-- Squared flag -->
   

Where to Look First

• Demo Page – Visual reference for all flags and usage.
• ISO 3166-1-alpha-2 Codes – List of country codes (e.g., us, gb, jp).
• sass/_variables.scss – Customization options for SASS.

Implementation Patterns

Core Workflows

1. Basic Flag Display:

   <!-- Default (proportional) -->
   <span class="fi fi-us"></span>
   
   <!-- Squared version -->
   <span class="fi fi-us fis"></span>
   

2. Dynamic Flag Rendering (Laravel Blade):

   @php
   $countryCode = 'ca'; // Canada
   $isSquared = true;
   @endphp
   
   <span class="fi fi-{{ $countryCode }} {{ $isSquared ? 'fis' : '' }}"></span>
   

3. SASS Integration (Custom Build with Country Exclusion):

   @use "node_modules/flag-icons/sass/flag-icons" with (
     $flag-icons-included-countries: ("us", "ca", "jp") // Only include these flags
   );
   

   Compile with npm run dev or laravel-mix. Note: as of v7.6.0, the file reference used by the "exclude countries" workflow was corrected — if you previously had to patch paths manually, you can drop that workaround.

4. Flag as Background Image:

   .country-badge {
     background: url('/node_modules/flag-icons/flags/1x1/us.svg') no-repeat center;
     background-size: contain;
   }
   

5. Accessibility:

   <span class="fi fi-gb" aria-label="United Kingdom"></span>
   

Integration Tips

• Laravel Mix/Webpack: Import the CSS in resources/js/app.js:

  import 'flag-icons/css/flag-icons.min.css';
  

  Ensure the flags/ directory is copied to public/ via mix.copy().

• Dynamic Country Codes: Fetch codes from an API (e.g., REST Countries) and map them to flags.

• Dark Mode: Use SASS variables to override colors:

  @use "node_modules/flag-icons/sass/flag-icons" with (
    $flag-icons-bg: #f0f0f0, // Light background for flags
    $flag-icons-opacity: 0.8
  );
  

• Trimming the Bundle: The $flag-icons-included-countries option is now reliably resolved (v7.6.0 fixed an outdated file reference); use it to cut the build down to only the flags your app actually shows.

Gotchas and Tips

Pitfalls

1. Missing Flags:

   • If a flag doesn’t render, verify the ISO 3166-1-alpha-2 code (e.g., gb for UK, not uk).
   • Check the demo page for valid codes.

2. SASS Path Issues:

   • Ensure $flag-icons-path in SASS points to the correct directory (default: node_modules/flag-icons/flags).
   • If using Laravel Mix, run npm run dev after updating SASS variables.
   • v7.6.0 corrected the file reference used when excluding countries — verify you're on the latest patch if the exclude list silently produced no output.

3. CDN Caching:

   • Hard-cache the CDN URL in production to avoid layout shifts:

     <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/lipis/[email protected]/css/flag-icons.min.css" integrity="..." crossorigin="anonymous">
     

4. File Size:

   • The full CSS (~10KB) includes all flags. Use SASS to exclude unused countries for smaller builds.

5. SVG Optimization:

   • Flags are SVGs. If using inline SVGs (e.g., <img src="...">), ensure your Laravel asset pipeline handles them (e.g., via mix.copy()).

6. Rendering glitches (fixed in v7.6.0):

   • A color bleed bug on Chrome was fixed in v7.6.0. If your project shipped any CSS workarounds (extra overflow: hidden, contain, or filter hacks) to mask this, remove them after upgrading.
   • Several flags were corrected (Panama, Vanuatu, Burkina Faso, New Caledonia, Ivory Coast/Côte d'Ivoire, Yemen, Ethiopia, Ascension Island). If any of these countries appear in your UI, bumping to 7.6.0 is worth a visual spot-check on flags previously worked around.

Debugging

• Flag Not Loading?

  • Check the browser’s Network tab for 404s on SVG files (e.g., /flags/1x1/us.svg).
  • Verify the flags/ directory is accessible in public/.

• SASS Errors:

  • Run npm run dev to recompile SASS after changes.
  • Check for typos in country codes (e.g., fi-gr vs. fi-gb).

• Visual regressions vs. old version?

  • v7.6.0 ships corrected artwork for several flags (see above). If a flag suddenly looks different after upgrade, confirm against the demo page and check the changelog for that country.

Extension Points

1. Custom Flags:

   • Add your own SVGs to the flags/ directory and reference them with fi-custom (requires CSS updates).

2. Flag Size:

   • Use fi-2x, fi-3x, etc., for larger flags:

     <span class="fi fi-us fi-2x"></span>
     

3. Flag Animations:

   • Animate flags with CSS:

     .fi.fi-us {
       transition: transform 0.3s;
     }
     .fi.fi-us:hover {
       transform: scale(1.2);
     }
     

4. Laravel View Composers:

   // app/Providers/AppServiceProvider.php
   View::composer('*', function ($view) {
       $view->with('countryFlags', ['us', 'ca', 'gb']); // Preload common flags
   });
   

5. Localization:

   • Pair flags with country names using Laravel’s trans():

     <span class="fi fi-fr"></span> {{ trans('countries.fr') }}