npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@johnmorrisdotca/chizu

v1.17.0

Published

Chizu 地図 — SVG maps for JavaScript: world and country outlines, 33 countries' regions, English/Japanese names, pan and zoom, insets, geography quizzes and numbered callouts. Zero dependencies.

Readme

Chizu is the world as SVG, and the things a person does with a map: look for a country, say which country a shape is, put a number on each of twenty places so a printed sheet can name them. It began in the geography quizzes of Itsutsu and a Japanese study app by the same author, and was taken out of both. Names are in English and Japanese today; Spanish, German and Chinese are planned, not started. It runs in the demo.

In 30 seconds

npm install @johnmorrisdotca/chizu
import WORLD from "@johnmorrisdotca/chizu/world";
import { drawChizu } from "@johnmorrisdotca/chizu/draw";
import { findQuestion, layoutCallouts, seededRandom } from "@johnmorrisdotca/chizu";

drawChizu(WORLD, { tones: { BR: "selected" }, language: "en" });   // the world as SVG text, Brazil lit, names in English

findQuestion(WORLD, "FR", seededRandom(7));
// { target: "FR", choices: ["BE", "FR", "DE", "CH"], answerIndex: 1 }: France among its look-alikes, the same every time

layoutCallouts(WORLD, { codes: ["JP", "BR", "EG", "AU"], radiusRatio: 0.02 });
// [{ code: "JP", number: 1, start: [455.6, 211], circle: [476.6, 268.1], radius: 20 }, …]

And in a page, a map to drag, zoom and press, by touch and mouse, with the keyboard to move and zoom it:

import WORLD from "@johnmorrisdotca/chizu/world";
import { mountChizu } from "@johnmorrisdotca/chizu/mount";

mountChizu(document.getElementById("map")!, { map: WORLD, onSelect: (code) => console.log(code) });

Who it is for

  • A site that shows the world: where members live, a figure for every country. projectPoint puts a longitude and latitude on the canvas, and the world pans round without stopping.
  • A site that shows a country's regions: the states of the United States, Brazil or Germany, the provinces of Canada or China, the prefectures of Japan.
  • Geography quiz and study sites that want "which country is this?" with look-alike wrong answers built in (neighbours first, then the same continent, then whatever is nearest), questions that come out the same from the same seed, and names in English and Japanese.
  • Printable sheets and worksheets, where a map has to be labelled with numbers in the sea, never on the land, with leader lines that never cross and cross as little land as they can.
  • Anyone who needs country and region outlines and names as plain data, rebuilt from a public-domain source.

Features

Each example is run in CI (pnpm test:readme). Pictures: What's in it.

  • The world, and 253 countries each on its own. The world is one canvas of 173 countries, centred on 155°E so the Pacific is not cut; 62 too small for 1:110m are opt-in dots (/small-states). Each of the 253 countries and territories is also a map of its own, from 1:50m outlines (1:10m for the small ones, so Singapore and Malta are shapes, not hexagons).
  • The regions of 33 countries, each its own file, 1,378 in all, from the 50 states and Washington DC to Japan's 47 prefectures (docs/maps.md counts each).
  • ISO 3166-2 codes on the regions (CA-ON, US-TX, JP-13), 1,371 of the 1,378, joined at build time from kuni 国, so figures keyed by ISO code colour the map; the 7 without one are listed in docs/iso-codes.md.
import WORLD from "@johnmorrisdotca/chizu/world";
import { loadCountry, loadDivisions } from "@johnmorrisdotca/chizu/load";

console.log(WORLD.regions.length, (await loadCountry("sg"))!.name);   // 173 Singapore
const canada = (await loadDivisions("ca"))!;
console.log(canada.regions.length, canada.regions.find((region) => region.iso === "CA-ON")!.name);   // 13 Ontario
  • Seas, lakes, rivers, mountains and capitals, a layer each map turns on (features: ["water"]): oceans, seas, bays and straits, lakes, rivers, deserts, ranges, peaks and capitals, named in English and Japanese and read in kana; searched, framed, chosen and numbered like any place.
import { loadFeatures } from "@johnmorrisdotca/chizu/load";
import { findFeatures } from "@johnmorrisdotca/chizu";

const [caspian] = findFeatures((await loadFeatures("world"))!.features, "Caspian");
console.log(caspian!.code, caspian!.name, caspian!.kind);   // Q5484 Caspian Sea sea
  • Airports and harbours, ports marks the 600 busiest airports and 1,081 harbours, each list its own entry, named in English and Japanese, more of them as the window closes in; runways draws each airport's runways from their measured ends. docs/ports.md.
import WORLD from "@johnmorrisdotca/chizu/world";
import { drawChizu } from "@johnmorrisdotca/chizu/draw";
import { AIRPORTS } from "@johnmorrisdotca/chizu/airports";
import { HARBOURS } from "@johnmorrisdotca/chizu/harbours";

const svg = drawChizu(WORLD, { ports: [...AIRPORTS, ...HARBOURS], language: "ja" });
console.log(AIRPORTS.length, HARBOURS.length, svg.includes('data-port="hnd"'));   // 600 1081 true
  • Names in English and Japanese today. Every country is named in both, with the everyday short name (アメリカ for アメリカ合衆国) and the reading in kana, and 1,377 of the 1,378 regions have a Japanese name, read from kuni 国 at build time. Spanish, German and Chinese names are planned and not started; any other language is a table of your own (Languages).
import { CHIZU_COUNTRIES, countryByCode } from "@johnmorrisdotca/chizu/names";

const brazil = countryByCode("BR")!;
console.log(CHIZU_COUNTRIES.length, brazil.name, brazil.nameJa);   // 253 Brazil ブラジル
  • Framing and zoom in ten steps, 1× to 10×, a window on a region, a square for an icon, a fit for a group. A region drawn in a box is framed where it is drawn, not out in the Pacific.
  • A world that goes round. East and west never stop: the canvas is drawn again either side of itself wherever the window overhangs.
import WORLD from "@johnmorrisdotca/chizu/world";
import { drawChizu } from "@johnmorrisdotca/chizu/draw";
import { regionBox } from "@johnmorrisdotca/chizu";
import { loadDivisions } from "@johnmorrisdotca/chizu/load";

const hawaii = regionBox((await loadDivisions("us"))!, "HI", 1.5);
console.log(Math.round(hawaii.width), Math.round(hawaii.height));    // 228 152
const edge = drawChizu(WORLD, { box: { x: 700, y: 0, width: 600, height: 632 } });
console.log(edge.match(/data-code="RU"/g)!.length);                  // 2: Russia again, past the edge
  • A callout placer. Numbered circles in open water, no two leaders crossing, each crossing as little land as it can; the same every time.
  • Quiz distractors. The wrong answers for "which one is this?", tempting for a reason, the same for the same seed.
  • Pasted names to places. A list somebody typed becomes the regions it names, with what matched nothing said back.
  • Longitude and latitude to the canvas, and back, held to d3-geo's own to a hundredth of a unit.
import WORLD from "@johnmorrisdotca/chizu/world";
import { layoutCallouts, pickDistractors, placesFromText, projectPoint } from "@johnmorrisdotca/chizu";

console.log(layoutCallouts(WORLD, { codes: ["BR", "US", "EG", "AU"], radiusRatio: 0.02 }).map((spot) => spot.code));
console.log(pickDistractors(WORLD, "DE", { count: 3 }));                // [ 'LU', 'NL', 'AT' ]: its neighbours first
console.log(placesFromText("Brazil, フランス\nNarnia", WORLD.regions));   // { codes: [ 'BR', 'FR' ], missing: [ 'Narnia' ] }
console.log(projectPoint(WORLD, -46.63, -23.55));                       // São Paulo on the canvas: [ 939.9, 382.7 ]
  • The city scale. A local projection takes a map past the 10× step to a venue: your own GeoJSON, pictures at their true size, callouts and a scale bar. docs/city.md.
  • Drawn as SVG text, with tones, a colour of your own for any region, labels, insets and callouts, for a server, an email, a build step or innerHTML.
import WORLD from "@johnmorrisdotca/chizu/world";
import { localMap } from "@johnmorrisdotca/chizu";
import { drawChizu, drawLocal } from "@johnmorrisdotca/chizu/draw";

console.log(drawChizu(WORLD, { tones: { BR: "selected" }, language: "en" }).includes('data-code="BR"'));   // true
console.log(drawLocal(localMap({ centre: [-0.1276, 51.5072], widthMetres: 300 }), {}).startsWith("<svg"));   // true
  • Dragged and zoomed in any page: drag, buttons, the wheel or a pinch, arrow keys, a press to choose; words for a screen reader in English and Japanese.
import WORLD from "@johnmorrisdotca/chizu/world";
import { mountChizu } from "@johnmorrisdotca/chizu/mount";

mountChizu(document.getElementById("map")!, { map: WORLD, onSelect: (code) => console.log(code) });
  • No dependencies, no network requests, nothing stored outside the page.

What's in it

Each picture is the real map, drawn by the package and taken from the demo with pnpm screenshots:readme, in light and dark.

Build a map, locator or quiz embed. The embed guide covers attributes, properties, iframe parameters and event messages. Map/locator embeds support per-place colors and capital="off"; builder links retain both. See colours and markers.

Use it in your project

Chizu is five things, each usable without the others: the engine (framing, zoom, insets, callouts, distractors, pasted names; plain functions over plain data), the maps (the world, a country alone, a country's regions: data, one file each), the drawing (SVG text), the page (a mounted map) and the names (every country in both languages, with no outlines). The table under API says which entry holds which.

Install under another name

npm install maps@npm:@johnmorrisdotca/chizu
import { wholeMapBox } from "maps";
import WORLD from "maps/world";
console.log(wholeMapBox(WORLD));

Install

npm install @johnmorrisdotca/chizu
# or: pnpm add @johnmorrisdotca/chizu
# or: yarn add @johnmorrisdotca/chizu

It is ES modules only, with its types included, and needs Node 22 or later when it runs outside a browser. A page with no bundler imports from a CDN (@1 is the major version): see the first example under Examples.

1. The engine alone, on a server

import { layoutCallouts, regionBox, zoomBox, zoomToFit } from "@johnmorrisdotca/chizu";
import { loadDivisions } from "@johnmorrisdotca/chizu/load";

const germany = (await loadDivisions("de"))!;               // 16 states, one file, fetched when asked for
regionBox(germany, "BY", 1.5);                              // a window tight on Bavaria, in a frame 1.5 times as wide as tall
zoomToFit(germany, ["BY", "BW"]);                           // { zoom: 1, centre: { x: 518.8, y: 868.2 } }
layoutCallouts(germany, { codes: germany.regions.map((r) => r.code) });   // sixteen numbered circles for a sheet

Every function takes a map and returns new values; none changes what it was given, and none needs a browser.

2. One map in a page

import { mountChizu } from "@johnmorrisdotca/chizu/mount";
import { loadCountry } from "@johnmorrisdotca/chizu/load";

const map = await loadCountry("jp");                        // Japan alone, from 1:50m outlines
const mount = mountChizu(document.getElementById("map")!, { map: map!, language: "ja" });
mount.zoomBy(1);

3. A bundler, and a framework

Each country's map is its own file and its own dynamic import (@johnmorrisdotca/chizu/load holds one import() for each), so a bundler makes a chunk of every one and a page fetches only the one it draws. The world is 170 kB (61 kB gzipped). A map is a plain object, so it serialises and caches as it is.

What a developer gets

  • Plain data. A ChizuMap is { id, kind, name, nameJa, width, height, wraps, projection, insets, regions }, and a region is { code, name, nameJa, reading, group, path, bbox, centroid, neighbors }. Your own map (a floor plan, a game board) is the same shape, and everything in the engine works on it.
  • The look comes from custom properties (--cz-*, --czm-*), light and dark; nothing is branded.
  • TypeScript types for all of it, each export with a doc comment.

In a framework

One call takes an element and hands back an object with destroy(): mount when the page has the element, destroy when it lets it go. docs/frameworks.md has it in React, Vue, Svelte and Angular.

Register a tag once and use it directly in React 19:

import "@johnmorrisdotca/chizu/element/define";
export function Japan() { return <chizu-map region="divisions-jp" highlight="JP-13" />; }

Vue needs isCustomElement: tag => tag.startsWith("chizu-") in its template compiler options:

<script setup>
import "@johnmorrisdotca/chizu/element/define";
</script>
<template><chizu-map region="world" /></template>
<script>
  import "@johnmorrisdotca/chizu/element/define";
</script>
<chizu-quiz region="world" seed="7"></chizu-quiz>

Use it anywhere

The demo, the docs (English and Japanese) and the embed page. Each way below is a tested file in examples/ (pnpm test:usage).

Guides: script tag, Vite and webpack, React, Vue, Svelte, Angular, iframe, TypeScript and Node.

Examples

Each example is a whole recipe: copy it and it works. They are run in CI against the built package (pnpm test:readme), so none of them is a guess, and the output shown is what they print.

A map in a page, with no bundler

Save this as a file and open it: a world you can drag, zoom with the buttons, the wheel or a pinch, and press. The two modules come from a CDN; @1 is the major version.

<!doctype html>
<meta charset="utf-8">
<title>A map</title>
<div id="map" style="height: 70vh"></div>
<script type="module">
  import WORLD from "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/chizu@1/dist/world-entry.js";
  import { mountChizu } from "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/chizu@1/dist/mount-entry.js";

  const map = mountChizu(document.getElementById("map"), {
    map: WORLD,
    language: "en",
    onSelect: (code) => console.log("chosen:", code), // "JP", or null when the same place is pressed again
  });
  map.select("JP"); // choose Japan and zoom to it
</script>

The world as an image, on a server

drawChizu is a string of SVG, so a server, a build step or an email can make a map with no browser. Here Japan is lit, the names are in Japanese, and the style travels inside the image.

import WORLD from "@johnmorrisdotca/chizu/world";
import { drawChizu } from "@johnmorrisdotca/chizu/draw";

const svg = drawChizu(WORLD, { tones: { JP: "selected" }, language: "ja", style: true });
console.log(svg.startsWith("<svg"), svg.includes('data-code="JP"'), svg.length > 100_000);
// await writeFile("japan.svg", svg);   // or hand it to a response, or put it in innerHTML
true true true

Frame a region and fit a group

A window is a box in the map's own units. regionBox is tight on one shape, zoomToFit finds the closest of the ten zoom steps that holds a group, and loadDivisions fetches one country's regions only when they are asked for.

import { regionBox, zoomToFit } from "@johnmorrisdotca/chizu";
import { loadDivisions } from "@johnmorrisdotca/chizu/load";

const germany = (await loadDivisions("de"))!;   // 16 states, one file
const bavaria = regionBox(germany, "BY", 1.5);   // a window tight on Bavaria, 1.5 times as wide as tall
console.log(Math.round(bavaria.width), Math.round(bavaria.height));
console.log(zoomToFit(germany, ["BY", "BW"]));   // the closest step that holds both south-western states
834 556
{ zoom: 1, centre: { x: 518.82, y: 868.1949999999999 } }

Which country is this?

findQuestion makes a question: the target and three look-alikes, in an order the seed fixes, so a quiz can be replayed and a server can check an answer without keeping the question.

import WORLD from "@johnmorrisdotca/chizu/world";
import { findQuestion, pickDistractors, seededRandom } from "@johnmorrisdotca/chizu";

const question = findQuestion(WORLD, "FR", seededRandom(7))!;
console.log(question);
console.log(question.choices[question.answerIndex] === question.target);
console.log(pickDistractors(WORLD, "DE", { count: 3 }));   // neighbours first
{ target: 'FR', choices: [ 'BE', 'FR', 'DE', 'CH' ], answerIndex: 1 }
true
[ 'LU', 'NL', 'AT' ]

Number twenty places for a printed sheet

layoutCallouts puts a numbered circle for each place in open water, with a leader line from the circle to its place and no two leaders crossing. drawChizu draws them, so the sheet is one string.

import WORLD from "@johnmorrisdotca/chizu/world";
import { drawChizu } from "@johnmorrisdotca/chizu/draw";
import { layoutCallouts } from "@johnmorrisdotca/chizu";

const codes = ["JP", "CN", "KR", "IN", "AU", "NZ", "US", "CA", "MX", "BR", "AR", "GB", "FR", "DE", "IT", "ES", "RU", "EG", "ZA", "KE"];
const spots = layoutCallouts(WORLD, { codes, radiusRatio: 0.016 });
console.log(spots.length, spots[0]!.code, spots[0]!.number, spots[19]!.code, spots[19]!.number);
const sheet = drawChizu(WORLD, { callouts: { codes, radiusRatio: 0.016 }, language: "en", style: true });
console.log(sheet.includes("cz-callout"));
20 JP 1 KE 20
true

Seas, lakes and rivers

loadFeatures fetches a map's named features; findFeatures finds one by English, Japanese or kana; drawChizu draws the water and lights it; and featureMap makes the layer a map, so a quiz asks "which sea is this?".

import WORLD from "@johnmorrisdotca/chizu/world";
import { drawChizu } from "@johnmorrisdotca/chizu/draw";
import { loadFeatures } from "@johnmorrisdotca/chizu/load";
import { featureMap, findFeatures, findQuestion, seededRandom } from "@johnmorrisdotca/chizu";

const layer = (await loadFeatures("world"))!;
const [caspian] = findFeatures(layer.features, "かすぴ");
console.log(caspian!.code, caspian!.name, caspian!.kind, caspian!.reading);
const svg = drawChizu(WORLD, { features: ["water"], featureLayer: layer, tones: { [caspian!.code]: "selected" } });
console.log(svg.includes('data-tone="selected"'), findQuestion(featureMap(WORLD, layer, ["water"]), caspian!.code, seededRandom(2))!.choices.length);
Q5484 Caspian Sea sea かすぴかい
true 4

Every country's name, in two languages

The table of countries has no outlines, so a page that only needs names loads 56 kB (10 kB gzipped). nameOf picks the language; reading is the kana.

import { CHIZU_COUNTRIES, countryByCode } from "@johnmorrisdotca/chizu/names";

const japan = countryByCode("JP")!;
console.log(japan.name, japan.nameJa, japan.reading, japan.group);
console.log(CHIZU_COUNTRIES.length, CHIZU_COUNTRIES.filter((country) => country.hasDivisions).length);
Japan 日本 にほん Asia
253 33

A look of your own

The drawing and the mounted map are coloured by custom properties, so a page changes them in CSS and nothing in JavaScript. This one is a map of a night sky.

.chizu {
  --cz-sea: #101a2e;
  --cz-land: #2c3e5c;
  --cz-line: #6d86b0;
  --cz-selected: #ffd23f;
  --cz-ink: #e8eefc;
}
.chizu-map { --czm-accent: #ffd23f; }

A map you steer from your own code

A mounted map is an object: choose, show, tone and count, and listen for every move.

import WORLD from "@johnmorrisdotca/chizu/world";
import { mountChizu } from "@johnmorrisdotca/chizu/mount";

const mount = mountChizu(document.querySelector<HTMLElement>("#map")!, {
  map: WORLD,
  selectable: false,                                  // a quiz: looked at, not chosen
  onView: (view) => console.log(view.zoom, view.box),
});
mount.show(["FR", "DE"]);                             // zoom to a pair
mount.set({ tones: { FR: "correct", DE: "wrong" } }); // colour them
mount.zoomBy(1);                                      // one step in
mount.reset();                                        // the whole map again
mount.destroy();                                      // when the page lets it go

A country's regions, one at a time

Every country is its own file, so a page that draws one country never loads another. loadCountry is a country alone and loadDivisions is its regions.

import { loadCountry, loadDivisions, COUNTRY_CODES, DIVISIONS_CODES } from "@johnmorrisdotca/chizu/load";

const france = (await loadDivisions("fr"))!;
console.log(france.name, france.regions.length, france.regions[0]!.name);
const ireland = (await loadCountry("ie"))!;
console.log(ireland.id, ireland.kind, COUNTRY_CODES.length, DIVISIONS_CODES.length);
France 96 Ain
country-ie country 253 35

Maps

| Map | Entry | What it is | Size | | --- | --- | --- | --- | | The world | @johnmorrisdotca/chizu/world | 173 countries, Natural Earth at 1:110m | 170 kB | | The world drawn finer | loadWorldDetail() from @johnmorrisdotca/chizu/load | the same 173 countries on the same canvas, at 1:50m, for a map zoomed in (mountChizu's detail) | 1.3 MB, fetched only when asked for | | A country alone | @johnmorrisdotca/chizu/countries/<code> or loadCountry("<code>") | 253 countries and territories at 1:50m (1:10m under 60,000 km²), on a canvas of their own whose longer side is 1,000 | 16 kB for Japan, 157 kB for Canada | | A country's regions | @johnmorrisdotca/chizu/divisions/<code> or loadDivisions("<code>") | 33 countries, Natural Earth admin-1 at 1:10m; dated maps vn-2025, gb-2025 (docs/maps.md) | 203 kB for Germany, 1.8 MB for Russia | | Japan's prefectures | divisions/jp or loadDivisions("jp") | 47 prefectures, Natural Earth admin-1 at 1:10m, with Okinawa and the outlying islands in boxes | 186 kB | | A map's seas, lakes, rivers, mountains and capitals | @johnmorrisdotca/chizu/features/<map> or loadFeatures("<map id>") | 286 maps' named features on their own canvases: docs/features.md | 203 kB for the world, 29 kB for Japan's prefectures |

The codes are ISO 3166-1 alpha-2, in lower case in a file's name (fr), and Natural Earth's own three letters for the few places that have none. CHIZU_COUNTRIES (from @johnmorrisdotca/chizu/names) lists every country with its names, and says which have a map of their own regions.

The 33 countries with regions are Argentina, Australia, Austria, Belgium, Brazil, Canada, Chile, China, Colombia, France, Germany, India, Ireland, Italy, Japan, Malaysia, Mexico, the Netherlands, New Zealand, Norway, Peru, the Philippines, Poland, Russia, South Korea, Spain, Sweden, Switzerland, Taiwan, Thailand, the United Kingdom, the United States and Vietnam.

Notes on the maps: how Japan's prefectures are numbered, grouped and boxed, what a country alone leaves out (France is the mainland and Corsica) and what the world leaves out, in docs/maps.md.

The canvas and the codes

The map data guide explains the canvas, paths, place codes and neighbour lists.

ISO codes

The ISO joins list the codes and exceptions; map names list every name kept apart from kuni's, with its reason. The map data guide preserves the worked detail.

Framing a map

The full reference and examples are in the linked guide. See Framing a map.

Numbered callouts

layoutCallouts(map, request) puts a numbered circle for each region asked for in the open space around the land and gives back where each leader starts and where its circle sits. The request, the three things it weighs, polish: true for a printed sheet, and the lower levels (placeCallouts, calloutSpaces, calloutFaults) are in Numbered callouts.

Which one is this?

import { findQuestion, pickDistractors, seededRandom } from "@johnmorrisdotca/chizu";

pickDistractors(WORLD, "DE", { count: 3 });    // ["LU", "NL", "AT"]: its neighbours first
pickDistractors(WORLD, "JP", { count: 3 });    // ["KP", "KR", "TW"]: nothing touches Japan, so whatever is nearest
findQuestion(WORLD, "FR", seededRandom(7));    // the target and its choices in an order the seed fixes

A wrong answer is scored 100 for a land neighbour, 60 for sharing a group and up to 40 for being close (distractorScore), so the choices are places a person could take it for. With a random stream the best few are shuffled and cut so the same country is not asked with the same company every time; without one the answer is simply the best count. among limits the places that may be offered.

Continents and other groups

A group of places is a list of codes, and groupMap, groupBox and groupTones cut a map down to one, frame it and fade the rest: a continent, a UN M49 subregion, the regions of Japan, Canada or the United States, or a list a page names itself. The worked example, CHIZU_CONTINENTS, CHIZU_SUBREGIONS and regionGroups(map) are in Continents and other groups.

Pasted names

placesFromText(text, map.regions) is shown under Features. Case and surrounding space never matter, a name may be English, Japanese, the short Japanese or the reading, and a line that matches nothing is said back and never guessed at: "Tokyo" does not quietly become Tochigi. optionalEnding lets a pasted prefecture leave off its 県 or 府 (/[県府都道]$/u). countriesFromText does the same over the table of every country.

Longitude and latitude

projectPoint(WORLD, 139.69, 35.69) is Tokyo on the world's canvas, [457.5, 212.5], and unprojectPoint goes back. A map keeps how its canvas was made (projection). How each canvas was projected, and why projectPoint answers null on a country's regions: docs/map-data.md.

@johnmorrisdotca/chizu/world-geo is the same world before any projection: a GeoJSON FeatureCollection of 177 features (Natural Earth 5.1.2, 1:110m) in WGS84 [longitude, latitude] degrees, for d3-geo's geoOrthographic or any spherical view: the 173 countries of WORLD and four it leaves out (AQ, TF, CYN, SOL). It is its own entry (166 kB minified, 44 kB gzipped), so a flat map never loads it. Zoomed in, world-geo-detail (1:50m) and divisions-geo/<code> are the same in degrees: docs/maps.md.

import WORLD_GEO from "@johnmorrisdotca/chizu/world-geo";

const japan = WORLD_GEO.features.find((feature) => feature.properties.code === "JP")!;
console.log(WORLD_GEO.features.length, japan.properties.iso3, japan.properties.nameJa); // 177 JPN 日本

The city scale

Natural Earth stops at about a kilometre. Past it, localMap makes a map of a city or a venue from the GeoJSON and pictures you pass, in a transverse Mercator centred on the place (a canvas unit is metresPerUnit metres, held to the ellipsoid's own distances within 0.5%), and drawLocal draws it. Nothing is fetched and no map data is added: you pass the credit lines. docs/city.md has all of it.

import { localMap } from "@johnmorrisdotca/chizu";
import { drawLocal } from "@johnmorrisdotca/chizu/draw";

const pitch = '<svg viewBox="0 0 100 60"><rect width="100" height="60" fill="#9bd18a"/></svg>';
const map = localMap({ centre: [139.7006, 35.7004], widthMetres: 300, markers: [{ at: [139.7006, 35.7004], svg: pitch, bearing: 30, name: "Pitch" }], credits: ["Pitch made up for this example"] });
console.log(drawLocal(map, { labels: true }).includes(">Pitch</text>"));
true

Drawing a map

import { drawChizu } from "@johnmorrisdotca/chizu/draw";

drawChizu(map, {
  box,                                      // a window; default the whole map
  language: "ja",                           // names for a screen reader and the labels
  tones: { BY: "selected", NW: "correct" }, // selected, correct, wrong, hint, muted, faint, or any name x for the class cz-tone-x
  colors: { BY: "#2f6b4f", NW: "teal" },    // a fill of your own for a region; docs/colours.md
  callouts: ["BY", "NW", "SL"],             // or a full request, as layoutCallouts takes it
  labels: true,                             // names on the land, where they fit; or a list of codes
  interactive: true,                        // every region a thing to press
  cities: await loadKuniCities(),           // dots and names, more as the window closes in; from /cities
  cityOptions: { minPopulation: 500_000 },  // a fixed floor; labels: false draws the dots alone
  overlays: [{ kind: "mark", at: [35.68, 139.69], label: "Tokyo" }], // lines, marks and areas from lat/lon; docs/guides/overlays.md
  style: true,                              // carry CHIZU_STYLE inside, so the drawing stands alone as an image
});

It is a string, so it works on a server, in a build step, in an email or in innerHTML. Each region is a <g class="cz-region" data-code="…"> with a <title> and a <path class="cz-land"> for each piece, and a window that overhangs the world's seam draws the land again on the far side.

Playing with a map in a page

import { mountChizu } from "@johnmorrisdotca/chizu/mount";

const mount = mountChizu(element, { map, language: "ja", onSelect: (code) => …, onView: (view) => … });
mount.select("BY");   // choose a region and zoom to it
mount.show(["BY", "BW"]);   // look at these
mount.set({ tones: { BY: "correct" }, callouts: ["BY", "NW"] });
mount.setMap(otherMap);
mount.zoomBy(1);
mount.reset();
mount.destroy();

| Input | What it does | | --- | --- | | Drag | moves the map; a drag past the edge stops at it (not on the world, which goes round) | | The +, − and ⌂ buttons | zoom in and out in ten steps, and back to the whole map | | The wheel over the map, or a pinch | zoom a step about the pointer. With the pointer elsewhere the page scrolls, and a wheel that starts with the zoom already at its end scrolls the page too | | A press | chooses a region (and a second press on it, none) | | Arrow keys, +, -, 0 | move, zoom, and show the whole map, with the map focused |

cities, cityOptions and overlays are as drawChizu takes them (cities, overlays). selectable: false makes the map only looked at, which a quiz wants. Callouts are placed again for the window as it is after each move, and keep out from under the buttons.

API

Every fixed map and feature import is listed in the map-resource catalogue.

The documentation supplies checked examples, bilingual guides and local search. The API index retains export anchors.

The API reference lists every export of every entry point with its signature and its doc comment. It is made from the source by pnpm site, so it cannot fall behind the code.

| Entry | What it holds | | --- | --- | | @johnmorrisdotca/chizu | The engine: wholeMapBox, zoomBox, focusBox, regionBox, zoomToFit, shapeGlyphBox, MAP_ZOOM_LEVELS; insetFor, insetTransform; wrapOffsets, wrapIntoBox; overlaysSvg; mapOutlines, parseMapRings, landAnchor, pointInRing; layoutCallouts, placeCallouts, calloutFaults; findQuestion, pickDistractors, distractorScore; placesFromText; featureMap, featuresShown, findFeatures, featureKindName, featureKindOf; placeCities, cityPopulationFloor, windowKilometres; placePorts, portsInTier, portTierFor, portName, runwaysSvg; projectPoint, unprojectPoint; nameOf, chizuSay, CHIZU_STRINGS; seededRandom, shuffled; VERSION | | @johnmorrisdotca/chizu/element | ChizuMapElement, ChizuLocator, ChizuQuiz, defineMap, defineLocator, defineQuiz, loadElementMap, readMapData, CHIZU_ELEMENT_OPTION_KEYS; ChizuElementOptions | | @johnmorrisdotca/chizu/element/define | registers <chizu-map>, <chizu-locator> and <chizu-quiz> | | @johnmorrisdotca/chizu/draw | drawChizu, CHIZU_STYLE | | @johnmorrisdotca/chizu/mount | mountChizu, ensureChizuMapStyle, CHIZU_MAP_STYLE | | @johnmorrisdotca/chizu/names | CHIZU_COUNTRIES, CHIZU_SOURCE, countryByCode, countriesFromText | | @johnmorrisdotca/chizu/cities | loadKuniCities, CHIZU_CITY_TIERS: kuni's cities for drawChizu's cities (needs the optional peer @johnmorrisdotca/kuni 1.6.0 or later; its size is measured with kuni bundled in) | | @johnmorrisdotca/chizu/airports | AIRPORTS, AIRPORT_TIER_ENDS, AIRPORTS_CREDIT: for drawChizu's ports | | @johnmorrisdotca/chizu/harbours | HARBOURS, HARBOURS_CREDIT: for ports | | @johnmorrisdotca/chizu/runways | RUNWAYS, RUNWAYS_CREDIT: for drawChizu's runways | | @johnmorrisdotca/chizu/load | loadCountry, loadDivisions, loadFeatures, loadWorldDetail, COUNTRY_CODES, DIVISIONS_CODES, FEATURE_MAPS | | @johnmorrisdotca/chizu/world | the world, as the default export and as WORLD | | @johnmorrisdotca/chizu/small-states | withSmallStates: 62 small countries as dots | | @johnmorrisdotca/chizu/world-geo | the world as longitude/latitude GeoJSON for a spherical projection, as the default export and as WORLD_GEO | | @johnmorrisdotca/chizu/world-geo-detail | the 1:50m world in degrees, as the default export and as WORLD_GEO_DETAIL | | @johnmorrisdotca/chizu/divisions-geo | loadDivisionsGeo, DIVISIONS_GEO_CODES | | @johnmorrisdotca/chizu/divisions-geo/<code> | one country's regions in degrees, as the default export | | @johnmorrisdotca/chizu/countries/<code> | one country alone, as the default export | | @johnmorrisdotca/chizu/divisions/<code> | one country's regions, as the default export | | @johnmorrisdotca/chizu/features/<map> | one map's seas, lakes, rivers, landforms, peaks and capitals (world, divisions-jp), as the default export |

Every function is pure: it returns new values and never changes what it was given.

Theming

Nothing here is branded. The drawing and the mounted map are coloured by custom properties, and a page sets only the ones it wants different. They follow the device's light or dark setting; data-theme="light" or "dark" on <html> forces one.

The drawing (drawChizu), custom properties on .chizu:

| Property | What it colours | Light | Dark | | --- | --- | --- | --- | | --cz-sea | the sea | #cfe3ee | #18303d | | --cz-land | land | #e9e1c8 | #4a4a3d | | --cz-line | a border | #5d5a50 | #aaa592 | | --cz-inset | the dashed frame of an inset | #7a766a | #8f8b7a | | --cz-ink | a printed name | #1f2320 | #ece8dc | | --cz-selected | the tone selected | #ffd23f | #a8841a | | --cz-correct | the tone correct | #9bd6a8 | #2f6b45 | | --cz-wrong | the tone wrong | #f0a99b | #8a3a2c | | --cz-hint | the tone hint | #b7dcf4 | #2d5a78 | | --cz-muted | the tone muted | #d9d5c6 | #3a3a30 | | --cz-faint | the tone faint | #f3efe4 | #55554a | | --cz-callout | a callout's circle | #ffffff | #ece8dc | | --cz-callout-ink | a callout's number | #1f2320 | the same | | --cz-leader | a leader line and its dot | #3a3d38 | #ece8dc | | --cz-halo | the halo round a printed name | #f7f3e8 | #1d201e | | --cz-marine | a sea, under the land | #cfe3ee | #18303d | | --cz-water | a lake and a river | #a6cde6 | #2f6283 | | --cz-water-ink | the name of water | #2b5d84 | #9fcbe8 | | --cz-feature-line | a landform's name and outline, a peak | #6b5d45 | #cdbd97 | | --cz-feature-selected | a chosen feature | #4f9bd6 | #3f8cc6 | | --cz-airport | an airport's mark | #2f78b5 | #7cc4ff | | --cz-harbour | a harbour's ring | #1f8a6a | #5fd3a6 | | --cz-runway | a runway | #4b4f58 | #b9bdc7 | | --cz-font | the font of names and numbers | the system's, with Hiragino and Noto Sans JP for Japanese | the same |

The mounted map (mountChizu), custom properties on .chizu-map:

| Property | What it colours | Light | Dark | | --- | --- | --- | --- | | --czm-ink | the buttons' ink and the line of words | #1f2320 | #ece8dc | | --czm-surface | the buttons | #fbf8f1 | #1d201e | | --czm-rule | the frame and the buttons' outline | #bdb6a4 | #4a4d46 | | --czm-accent | the focus ring | #b5452c | #ff8a6b |

The parts of the drawing carry classes (cz-region, cz-land, cz-sea, cz-inset, cz-label, cz-callout, cz-leader, cz-callout-circle, cz-callout-number, cz-tone-<name>) for anything a property cannot reach. The demo's page is the worked example, on the family's stylesheet, demo/family.css.

Limits

All of these are held by tests, and the ones with a name are exported.

| Limit | Value | Where | | --- | --- | --- | | Zoom | ten steps, 1× to 10× | MAP_ZOOM_LEVELS | | The world | 173 countries on a canvas 1,000 wide and 489 tall | WORLD | | Countries alone | 253, on a canvas whose longer side is 1,000 | CHIZU_COUNTRIES | | Countries with regions | 33 | DIVISIONS_CODES | | Dated maps of regions | 2 (VN-2025, GB-2025) | DIVISIONS_CODES | | A callout's circle | 3% of the window's width unless asked otherwise | CALLOUT_RADIUS_RATIO | | Callouts that cross | none, for the maps and lists the tests place, polished or not | calloutFaults | | Wrong answers | 3 unless asked otherwise, drawn from the best count + 3 | pickDistractors | | Window copies drawn on the world | at most 4, however wrong the window | wrapOffsets |

Placing callouts takes about 70 ms for twenty countries and 240 ms for France's 96 départements (on a laptop); polish: true adds up to a few seconds. Nothing here runs on a timer, and a mounted map draws only when it is moved, zoomed or told something new.

Accessibility

  • A screen reader hears the map. The mounted map is a focusable stage with the name "Map of Japan" (in Japanese, 日本の地図) and a description of its keys. A polite line under it says what is chosen ("Japan chosen") or "Nothing chosen". The zoom buttons are real buttons labelled "Zoom in", "Zoom out" and "Show the whole map", and a button that cannot do anything now is disabled.
  • The drawing says what it is. drawChizu makes an svg with role="img" and an aria-label naming the map; each region carries a <title> with its name. With interactive: true the drawing is a role="group" and every region a role="button" with its name as its label, for a page to hand focus to.
  • The keyboard moves and zooms the map. Tab reaches the map, the arrow keys move it by 12 percent of the window, + and - zoom (= and _ too) and 0 shows the whole map; the focus ring is three pixels in the accent colour. The zoom buttons are reached with Tab and pressed with Enter or Space.
  • Touch targets. The zoom buttons are 44 by 44 pixels. A drag moves the map and not the page (touch-action: none on the stage only); the wheel over the map zooms it and anywhere else scrolls the page.
  • Reduced motion. Nothing in the package animates, so there is nothing for prefers-reduced-motion to change.
  • Colour. Land, sea and the six tones follow the device's light or dark setting. A tone (correct, wrong, selected) is a fill colour and a data-tone attribute and nothing more, so a page says so in words as well, as the demo's quiz does. The colour pairs in Theming have not been measured against WCAG contrast ratios.
  • Keyboard choice inside the map. Shift and an arrow key move the focus between places, Enter chooses one, Escape returns to the map; onHover and onFocus name the place (docs/embeds.md).
  • Not yet: Japanese read by a native reader. The words are listed beside their English in docs/strings-ja.md (see Languages).

Browser and runtime support

Any browser with ES2020 modules, pointer events and CSS aspect-ratio: Chrome and Edge 88, Safari 15, Firefox 89, all from 2021 on. The mounted map draws in the page's own DOM, with no shadow DOM and no CSS the page cannot reach. The demo is played in Chromium (phone and desk, with touch) and WebKit (phone); Firefox is not in that run. The package itself (everything but the page) needs no DOM: it runs in Node 22 or later (CI tests 22 and 24). Deno and Bun are not tested.

Languages

English and Japanese: the names of every country, of nearly every region and of most seas, lakes and rivers (kuni's, from Unicode CLDR and Wikidata, and Natural Earth's, from Wikidata; docs/features.md), the everyday short name where it is not the formal one (アメリカ), the reading in kana of every country and every prefecture, the words of the drawing and the mounted map (CHIZU_STRINGS), and the demo. Japanese: included; not yet reviewed by a native reader. Corrections welcome. The readings are kuni's, but for the three places kuni does not have, whose readings are hand-written, 3 of them (KANJI_READINGS in scripts/data-config.mjs); a name in katakana is its own reading. Every string of the board is listed beside its English in docs/strings-ja.md, and there is an issue template for fixing one. Any other language is a table of your own, passed beside these two: Natural Earth carries names in more than twenty.

Roadmap

What is planned and what is not: docs/roadmap.md.

Architecture

The engine, generated resources and browser layers are explained in the architecture guide; its complete source tree and build description are preserved there.

The name

Chizu (地図) is Japanese for "map": the everyday word, read ちず, as in 世界地図 (sekai chizu), a map of the world. It is written with 地, "ground", and 図, "diagram", and said in two beats, chi-zu. A map here is what it is in the word: a picture of the ground. (Wiktionary: 地図, which gives ちず as "map".)

Where it comes from, and where it is used

Chizu was built for Itsutsu, a site for board, puzzle, card and dice games, and for UmaKuma, a Japanese study app by the same author, where the map engine began as a way to learn the prefectures and the countries and to print numbered map sheets. Both import it. Tenka, the family's world-conquest game, draws a world of its own from the same Natural Earth file, by its own script.

Used by

  • Itsutsu, for its geography.
  • UmaKuma, a Japanese study app by the same author, for its map sheets and its which-prefecture and which-country questions.
  • REST in Pieces, a fake-data REST service, draws /maps/{code}.svg with Chizu: any country or region outlined, coloured and with its capital, when Chizu is installed beside it.

Using Chizu in something? Open an Add my project issue and we will add you.

The family

Chizu is one of forty-one packages, each made for the same site, each at github.com/johnmorrisdotca or github.com/spxis. The code of every one is MIT.

Games — board

  • Domino (ドミノ): dominoes and Mexican Train. Demo.
  • Gunjin (軍人): five hidden-rank strategy games with pass-the-device play. Demo.
  • Narabe (並べ): one rules engine for abstract board games, from gomoku and Reversi to Go and checkers. Demo.
  • Sugoroku (双六): backgammon and its variants, with the doubling cube and match play. Demo.
  • Tenka (天下): world conquest for two to six, on a map of the real world. Demo.

Games — cards & tiles

  • Fuda Cards (札): collectible card frames with a true thickness, foil, stacks, wear and a binder, as two web components. Demo.
  • Hitotsu (一つ): a colour-card shedding game for two to eight, with the house rules people play. Demo.
  • Jarajara (ジャラジャラ): mahjong tiles drawn as SVG, stacked layouts, and the matching solitaire Awase. Demo.
  • Kumimoji (組み文字): a crossword tile race, in English and Japanese kana. Demo.
  • Toranpu (トランプ): a deck of playing cards, card games with computer players, and solitaires. Demo.

Games — puzzles

  • Houseki (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. Demo.
  • Jirai (地雷): minesweeper on shaped grids with verified no-guess boards. Demo.
  • Karakuri (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. Demo.
  • Kazu (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. Demo.
  • Kyuubu (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. Demo.
  • Meikyuu (迷宮): mazes on squares, hexagons, triangles and circles, made from a seed and drawn through with a finger or the mouse. Demo.
  • Suido (水道): a pipe puzzle: turn the pieces until the water reaches every drain. Demo.
  • Tobiishi (飛び石): peg solitaire with nine boards and seeded solvable challenges. Demo.
  • Tsunagi (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. Demo.

Games — dice & random

  • Korokoro (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. Demo.
  • Tane (種): seeded random numbers and daily seeds, the same in every browser and on every server. Demo.

Language

  • Bushu (部首): find a kanji by the parts it is made of. Demo.
  • Hikidashi (引き出し): a drawer of small Japanese text tools: era dates, kanji numerals, readings and sentence difficulty. Demo.
  • Jisho (辞書): words of Japanese looked up by reading or written form, and the grades, JLPT levels, readings and look-alike pairs of 2,999 kanji. Demo.
  • Kotoba (言葉): word lists and word-game rules in English, French, German and Japanese. Demo.

Space Program X

  • Chikyu Earth (地球): a line-drawn globe that turns at the Earth's own rate, with an optional realistic Earth from space and markers for any place. Demo.
  • Hoshi Stars (星): the stars you can see without a telescope, with names, colours and distances, the constellations with their lines and boundaries, and the Messier objects, drawn on any of seven sky maps. Demo.
  • Uchusen Rockets (宇宙船): rockets drawn from sourced sizes, as line drawings and 3D views you can take apart and turn, with a check that a rocket really goes together. Demo.
  • Wakusei Planets (惑星): the Sun, the planets and their moons, as line drawings, shaded drawings and painted surface maps, with their real sizes, tilt and rotation. Demo.

Geography & data

  • address-plus (アドレスプラス): parse and format addresses in the United States, Canada, Japan, Australia, France, Germany and the United Kingdom. Demo.
  • Chizu (地図): maps of the world and of countries' regions, in English and Japanese, with a quiz and callouts. Demo.
  • Hako Devices (箱): line drawings and 3D views of computers, phones, consoles and NAS boxes, from published sizes. Demo.
  • Hata (旗): country and regional flags as SVG, at their true proportions and keyed by ISO code. Demo.
  • Koyomi Calendars (暦): calendar-page icons and whole months as SVG, in light and dark, with page-turning from one day to the next. Demo.
  • Kuni (国): countries and their regions, with ISO codes and names in English and Japanese. Demo.

Sports

  • Dougu Sports (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. Demo.
  • Kyogijo Stadiums (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. Demo.
  • Meigen Sports (名言): sports quotations and on-this-day history. Demo.
  • Senshu Jerseys (選手): sports jerseys, sweaters, kits, caps, helmets and retired-number banners as SVG, front and back, with optional 2.5D turning. Demo.
  • Taisen Brackets (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. Demo.

Developer tools

  • REST in Pieces (レスト・イン・ピーシーズ): seeded test data and REST APIs for frontend development, with latency and error drills. Demo.

This package is Chizu. The demos of all forty-one share one header and footer, so each links the rest.

Development

pnpm install
pnpm check          # lint, types and every test
pnpm data           # make src/data again from Natural Earth (downloads once into .cache/)
pnpm test:package   # pack, install and import it as somebody who installed it would
pnpm test:demo      # build the demo and play it in a real browser, at a phone's width and a desk's
pnpm site           # build the demo into site/, as the Pages workflow publishes it
pnpm docs:check    # typecheck and run the public API and guide examples
pnpm docs:site     # build the documentation and its local search index
pnpm screenshots:readme   # take the README's pictures from the built demo, in light and dark
pnpm test:readme    # run every example in the README against the built package

Contributing

See CONTRIBUTING.md. The commands are under Development.

Please follow the code of conduct. A way to make the callout placer or a parse of pasted names run for a very long time, or markup that gets out of the drawing, is for the security policy, not a public issue.

Changes

Every release, and what it adds, changes and fixes: CHANGELOG.md.

Licence

The code is MIT © John Morris. The outlines and the names are data from other people, under their own terms, written out in full in NOTICE.md (shipped in the package):

| Data | Made from | Terms | | --- | --- | --- | | The outlines of the world, of each country and of 33 countries' regions; the seas, lakes, rivers, landforms and peaks | Natural Earth 5.1.2, admin-0 countries at 1:110m, 1:50m and 1:10m, admin-1 states and provinces and the physical vectors at 1:10m | Public domain. Crediting the authors is unnecessary; it is done here anyway | | England, Scotland and Wales on gb-2025 | ONS councils of December 2025, named on CHIZU_SOURCE.ons | OGL v3.0: "Source: Office for National Statistics licensed under the Open Government Licence v.3.0", "Contains OS data © Crown copyright and database right 2025" | | The countries' names, short names, readings and continents; the regions' ISO 3166-2 codes; the names of Japan's prefectures and of the regions that are one ISO subdivision | kuni 国 1.6.0, read at build time, whose names are Unicode CLDR's and Wikidata's | kuni: MIT. CLDR: Unicode-3.0, whose notice is in NOTICE.md. Wikidata: CC0 | | The other regions' names in Japanese; the features' names | Natural Earth's names, which are Wikidata's, and Wikidata's | CC0 | | The readings of three places kuni does not have, and the names that tell two regions of one map apart | Written for this package | MIT |

Natural Earth is made by volunteers and supported by the North American Cartographic Information Society; their work is why a map like this can be free. Thank you.