Building TerraExplorer: A Country Discovery App with Vanilla HTML, CSS, and JavaScript

Website Start Page

I wanted to build something that made exploring the world feel interesting. Not a geography quiz, not a data dashboard. Just a simple, visual way to learn about countries. That idea turned into TerraExplorer.

The whole thing runs on vanilla HTML, CSS, and JavaScript. No React, no Vue, no build tools. Three HTML files, a couple of JSON animations, and a handful of free APIs.

What It Does

TerraExplorer has two main modes.

Explorer Mode is the main page. You hit a button, and it pulls up a random country. You get the flag, capital, population, currency, languages, an embedded Google Map, and a grid of photos from Unsplash. There is also an AI section powered by Google Gemini that generates a fun fact and a traditional dish for each country. You can filter by region if you want to narrow things down, and there is a history panel that keeps track of your last ten searches.

Discover Mode is an interactive world map built with Leaflet.js and TopoJSON data. Click any country and its territory fills in with its flag. A side panel slides in with the same country details, photos, and AI content. You can flag every country on the map or clear them all. Visited countries show up in green.

The two modes are connected. If you find a country in Explorer Mode, you can hit “Discover on Map” and it takes you straight to that country on the map with the AI content already loaded.

There is also a custom 404 page with an animated solar system and a Milky Way background, but that is mostly just for fun.

The Tech Stack

The project uses no frameworks and no bundler. Each page is a self-contained HTML file with inline styles and scripts.

For external libraries, I used Leaflet.js for the map rendering, TopoJSON Client to parse the world boundaries data, GSAP for the day/night SVG transition, and Lottie Player for a couple of small, animated icons in the header.

The APIs doing the heavy lifting are:

• RestCountries for all the country data
• Google Gemini for the AI-generated facts and dishes
• Unsplash for the photo grids
• Google Maps Embed for the map iframes
• ipapi.co for detecting the visitor’s country on first load

Things I Spent the Most Time On

The map flag-fill system. When you click a country on the map, every polygon that belongs to it fills with the country’s flag. This sounds straightforward, but countries like Indonesia or the Philippines have hundreds of individual islands, and each one needs its own SVG pattern element with the flag image fitted to that specific polygon’s bounding box. Getting the flag to look right on tiny islands and large landmasses alike took some iteration.

The Gemini integration. AI APIs are not always reliable, especially under free-tier rate limits. TerraExplorer cycles through four Gemini models with an eight-second timeout on each. If one model is slow or down, it moves to the next. Responses are cached in localStorage for 24 hours, so you only hit the API once per country.

The glassmorphism UI. The whole interface uses translucent blurred cards, styled with CSS backdrop-filter and custom properties for theming. There are two themes (dark and light), and switching between them triggers a GSAP animation on the background SVG where the sun rises, the moon drops, and the sky gradient shifts. Getting this to feel smooth without layout shifts was tricky.

The splash screen. The landing page opens with a pure CSS animated Earth, complete with continents made from box-shadows, orbiting moon, and a starfield. No images, no canvas, just CSS.

A Few Design Decisions

I went with glassmorphism for the visual style because it pairs well with the space and map backgrounds without competing for attention. The translucent cards let the background show through, which keeps the interface feeling light even when there is a lot of content on screen.

The app detects your country using IP geolocation and shows a small welcome toast after the splash screen. Tapping it loads your country’s card immediately. It only shows once per session.

For the photo grid, I added a full-screen lightbox with keyboard navigation and lazy preloading of adjacent images. There is also a “New photos” button that paginates through Unsplash results, so you are not stuck with the same set.

Everything that should persist does. Visited countries, flagged countries, AI responses, and search history all survive page reloads through localStorage.

The 404 Page

This one was a side project within the project. The 404 page has a CSS solar system with the Sun at the center, Earth orbiting it, and the Moon orbiting Earth. Behind everything is a multi-layered Milky Way simulation with nebula patches at different depths, dark dust lanes, and about 700 procedurally placed star dots. Dynamic stars continuously spawn and fade out on top of that. The sun has animated corona rays and expanding light rings, all generated by JavaScript.

It is completely unnecessary, but it was a good excuse to push what pure CSS and a bit of vanilla JS can do.

Deployment

The project is hosted on GitHub Pages. Since there is no build step, the deployment workflow just pushes the files as-is. The 404.html is picked up automatically by GitHub Pages for any unmatched route.

Try It Out

The live site is at TerraExplorer. The source code is on GitHub.

Connect With Me If you’d like to follow my work or get in touch, you can find me here:

You can explore the project in more detail through the links below, which include the source code and additional documentation. The code is publicly available on GitHub for testing, and the project is also deployed live.

• LinkedIn: [My LinkedIn Profile]
• GitHub: [My GitHub Profile]
• Kaggle: [My Kaggle Profile]
• Hugging Face: [My Hugging Face Profile]
• Tableau Public: [*My Tableau Public Profile*]
• My Website: *[My Official Website]*