---
id: "packages/active-geo/collection"
title: "World collection"
description: "The optional world-50m collection - Natural Earth countries, loaded on demand, its keys, rights and boundary policy."
url: "/packages/active-geo/collection"
locale: "en"
revision: "584edcd55419f8f1"
---

# World collection

The package carries no geography by default. One optional collection has its own entry:

```ts
import {
  loadWorld50m,
  world50m,
} from '@workspace/active-geo/collections/world-50m';

const features = await loadWorld50m(); // 242 areas, loaded on this call
```

**Example: Countries coloured by a measure**

Client: Runs entirely in your browser. Source: `examples/geo/world-map.tsx`.

```tsx
// apps/docs/examples/geo/world-map.tsx
'use client';

import {useEffect, useState} from 'react';

import {
  englishGeoTranslator,
  GeoMap,
  type GeoAreaFeature,
} from '@workspace/active-geo';
import {
  loadWorld50m,
  world50m,
} from '@workspace/active-geo/collections/world-50m';

// Invented values per country, joined by the collection's key (ADM0_A3).
const SHARE: Record<string, number> = {
  NLD: 82,
  BEL: 64,
  DEU: 71,
  FRA: 55,
  GBR: 48,
  ESP: 39,
  ITA: 44,
  POL: 31,
  SWE: 77,
  NOR: 69,
  USA: 58,
  CAN: 62,
  BRA: 27,
  IND: 19,
  JPN: 66,
  AUS: 52,
};

/**
 * The optional world collection (Natural Earth, 1:50m), loaded on demand,
 * coloured by a measure with a threshold scale. Hover or focus a country
 * for its value; the menu (right click, Shift+F10) holds the table and export.
 */
export default function WorldMap() {
  const [features, setFeatures] = useState<GeoAreaFeature[] | null>(null);
  useEffect(() => {
    let current = true;
    void loadWorld50m().then((loaded) => {
      if (current) setFeatures([...loaded]);
    });
    return () => {
      current = false;
    };
  }, []);
  if (!features) {
    return <p className="text-muted-foreground text-sm">Loading the map…</p>;
  }
  return (
    // The map takes the width of its container (a ResizeObserver);
    // in a centring layout the host gives it one.
    <div className="w-full">
      <GeoMap
        title="Share of online orders"
        projection="equal-earth"
        locale="en-GB"
        t={englishGeoTranslator}
        attribution={world50m.attribution}
        layers={[
          {
            type: 'area',
            id: 'countries',
            title: 'Countries',
            features,
            measures: [
              {
                id: 'share',
                label: 'Online share',
                semantics: {
                  kind: 'percent',
                  source: 'percentage-points',
                  preset: 'integer',
                },
              },
            ],
            data: Object.entries(SHARE).map(([key, share]) => ({
              key,
              values: {share},
            })),
            fill: {
              measure: 'share',
              scale: {type: 'threshold', thresholds: [30, 50, 70]},
            },
          },
        ]}
      />
    </div>
  );
}
```

- **Content**: Natural Earth Admin 0 – Countries at 1:50m, theme version 5.1.1 (release v5.1.2),
  242 areas keyed by `ADM0_A3` (a string). Join your records by that key; ISO codes are attributes,
  not keys.
- **Loading**: `world50m` (the metadata) loads no geometry; `loadWorld50m()` imports a separate
  chunk on its first call. No network request leaves your host.
- **Rights**: Natural Earth is in the public domain; crediting is optional.
  `world50m.attribution` is the suggested credit for `GeoMap`'s `attribution`, as the examples on
  this site show.
- **Boundaries**: Natural Earth's default de facto representation; a cartographic representation
  that takes no position on sovereignty.

The provenance of the collection (source, version, hashes, transformation) is in
`world50m` itself. The geometry is generated by the package's own build script and pinned by its
SHA-256; it is never edited by hand.