Countries API - CountriesDB

Documentation

Popular Frameworks

Complete integration examples for popular frameworks and routing libraries

The CountriesDB widget works seamlessly with all modern frameworks. Here are complete examples for popular frameworks:

React Router

Complete React Router v7 example demonstrating widget reload on route navigation. The widget automatically re-scans the DOM when navigating between routes using the `reload: true` option.

Requirements for API to Work:

This example uses the following configuration:

Required

1. Install the Widget Package

Install @countriesdb/widget using npm: npm install @countriesdb/widget

REQUIRED
All

2. Set Environment Variable

Create a .env file with your public key: VITE_COUNTRIESDB_PUBLIC_KEY=YOUR_PUBLIC_KEY

REQUIRED
All

3. Initialize Widget in Route Component

Set window.CountriesDBConfig and import the widget in your route component's useEffect hook.

REQUIRED
All

Example

React Router Integration
import { useEffect } from 'react';

export default function Countries() {
  useEffect(() => {
    const publicKey = import.meta.env.VITE_COUNTRIESDB_PUBLIC_KEY;
    
    ;(window as any).CountriesDBConfig = {
      publicKey,
    };

    if ((window as any).CountriesWidgetLoad) {
      (window as any).CountriesWidgetLoad({ reload: true });
    } else {
      import('@countriesdb/widget');
    }
  }, []);

  return (
    <div>
      <select
        className="country-selection"
        data-name="country1"
      />
      <select
        className="subdivision-selection"
        data-country="country1"
      />
    </div>
  );
}

Next.js

Complete Next.js App Router example demonstrating widget reload on page navigation. The widget automatically re-scans the DOM when navigating between pages using the `reload: true` option.

Requirements for API to Work:

This example uses the following configuration:

Required

1. Install the Widget Package

Install @countriesdb/widget using npm: npm install @countriesdb/widget

REQUIRED
All

2. Set Environment Variable

Create a .env.local file with your public key: NEXT_PUBLIC_COUNTRIESDB_PUBLIC_KEY=YOUR_PUBLIC_KEY

REQUIRED
All

3. Initialize Widget in Page Component

Set window.CountriesDBConfig and import the widget in your page component's useEffect hook.

REQUIRED
All

Example

Next.js Integration
'use client';

import { useEffect } from 'react';

export default function Countries() {
  useEffect(() => {
    const publicKey = process.env.NEXT_PUBLIC_COUNTRIESDB_PUBLIC_KEY;
    
    ;(window as any).CountriesDBConfig = {
      publicKey,
    };

    if ((window as any).CountriesWidgetLoad) {
      (window as any).CountriesWidgetLoad({ reload: true });
    } else {
      import('@countriesdb/widget');
    }
  }, []);

  return (
    <div>
      <select
        className="country-selection"
        data-name="country1"
      />
      <select
        className="subdivision-selection"
        data-country="country1"
      />
    </div>
  );
}

Vue

Complete Vue 3 example with Vue Router demonstrating widget reload on route navigation. The widget automatically re-scans the DOM when navigating between routes using the `reload: true` option.

Requirements for API to Work:

This example uses the following configuration:

Required

1. Install the Widget Package

Install @countriesdb/widget using npm: npm install @countriesdb/widget

REQUIRED
All

2. Set Environment Variable

Create a .env file with your public key: VITE_COUNTRIESDB_PUBLIC_KEY=YOUR_PUBLIC_KEY

REQUIRED
All

3. Initialize Widget in Route Component

Set window.CountriesDBConfig and import the widget in your route component's onMounted hook.

REQUIRED
All

Example

Vue Integration
<template>
  <div>
    <select
      class="country-selection"
      data-name="country1"
    />
    <select
      class="subdivision-selection"
      data-country="country1"
    />
  </div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue'

onMounted(() => {
  const publicKey = import.meta.env.VITE_COUNTRIESDB_PUBLIC_KEY

  ;(window as any).CountriesDBConfig = {
    publicKey,
  }

  if ((window as any).CountriesWidgetLoad) {
    (window as any).CountriesWidgetLoad({ reload: true })
  } else {
    import('@countriesdb/widget')
  }
})
</script>

Angular

Complete Angular 21 example with SSR/SSG demonstrating widget reload on route navigation. The widget automatically re-scans the DOM when navigating between routes using the `reload: true` option. Uses `afterNextRender` and `isPlatformBrowser` for SSR compatibility.

Requirements for API to Work:

This example uses the following configuration:

Required

1. Install the Widget Package

Install @countriesdb/widget using npm: npm install @countriesdb/widget

REQUIRED
All

2. Set Environment Configuration

Update src/environments/environment.ts with your public key: countriesDbPublicKey: 'YOUR_PUBLIC_KEY'

REQUIRED
All

3. Initialize Widget in Route Component

Set window.CountriesDBConfig and import the widget in your route component using afterNextRender with isPlatformBrowser check.

REQUIRED
All

Example

Angular Integration
import { Component, PLATFORM_ID, inject, afterNextRender } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { environment } from '../../environments/environment';

@Component({
  selector: 'app-countries',
  template: `
    <select
      class="country-selection"
      data-name="country1"
    ></select>
  `
})
export class CountriesComponent {
  private platformId = inject(PLATFORM_ID);

  constructor() {
    afterNextRender(() => {
      if (isPlatformBrowser(this.platformId)) {
        this.initWidget();
      }
    });
  }

  private initWidget(): void {
    const publicKey = environment.countriesDbPublicKey;

    ;(window as any).CountriesDBConfig = {
      publicKey,
    };

    // Reload widget when navigating to this route
    if ((window as any).CountriesWidgetLoad) {
      (window as any).CountriesWidgetLoad({ reload: true });
    } else {
      import('@countriesdb/widget');
    }
  }
}

SvelteKit

Complete SvelteKit example demonstrating widget reload on route navigation. The widget automatically re-scans the DOM when navigating between routes using the `reload: true` option.

Requirements for API to Work:

This example uses the following configuration:

Required

1. Install the Widget Package

Install @countriesdb/widget using npm: npm install @countriesdb/widget

REQUIRED
All

2. Set Environment Variable

Create a .env file with your public key: PUBLIC_COUNTRIESDB_PUBLIC_KEY=YOUR_PUBLIC_KEY

REQUIRED
All

3. Initialize Widget in Route Component

Set window.CountriesDBConfig and import the widget in your route component's onMount hook.

REQUIRED
All

Example

SvelteKit Integration
<script lang="ts">
  import { onMount } from 'svelte';
  import { PUBLIC_COUNTRIESDB_PUBLIC_KEY } from '$env/static/public';

  onMount(() => {
    const publicKey = PUBLIC_COUNTRIESDB_PUBLIC_KEY || 'YOUR_PUBLIC_KEY';

    ;(window as any).CountriesDBConfig = {
      publicKey,
    };

    if ((window as any).CountriesWidgetLoad) {
      (window as any).CountriesWidgetLoad({ reload: true });
    } else {
      import('@countriesdb/widget');
    }
  });
</script>

<select
  class="country-selection"
  data-name="country1"
></select>
<select
  class="subdivision-selection"
  data-country="country1"
></select>