> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loci.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# The map

> Datasets with colours and labels, the place filter, frames and their contents, drawing and area analysis, measuring, basemaps, and three-format export with restore.

This page is the map itself: what the floating panel offers your users, the hooks your app receives, and the controller you drive it with. Install and authentication are on the [overview](https://docs.loci.ng/sdks/web-overview.md).

## Options

```ts theme={null}
const controller = await createLociMap(container, options);
```

| Option | Type | What it does |
| - | - | - |
| `baseUrl` | `string` | The LOCI API origin. |
| `auth` | `{ apiKey }` or `{ shareToken }` | A scoped API key, or a read-only project share token. |
| `mapboxToken` | `string?` | Optional — omitted, the SDK borrows the deployment's token with your credential. |
| `orgId` / `projectId` | `string?` | Which datasets to list. With an API key both are optional — the key resolves its own org. |
| `title`, `subtitle` | `string?` | The floating panel's header. |
| `basemap` | `"dark" \| "light" \| "satellite" \| "streets" \| "3d"` | The first style; defaults to `dark`. Users switch from the toolbar. |
| `center`, `zoom` | `[lng, lat]`, `number` | The first view. |
| `analysisDatasetId` | `string?` | The dataset "Analyse this area" totals (defaults to the first population baseline the key can see). |
| `physicalDatasetId` | `string?` | The slope and land-cover baseline that enables off-road travel-time estimates. |
| `onAnalyze` | `(result: PolygonAnalysis) => void` | Every area analysis, for your own handling. |
| `onExport` | `(exp: MapExport) => void` | Every export (see below). Without it, exports download as files. |
| `onFrameSelect` | `(frames: Frame[]) => void` | A frame was selected on the grid. |
| `state` | `MapState?` | A previously exported map state to restore. |

## Datasets

The panel lists every dataset the key can read, each with:

* **A toggle.** Points, lines and polygons render as an overlay; a frame-keyed
  baseline renders as a choropleth with a legend, from zoom 8 up (the widget
  says "Zoom in to see…" when toggled at country zoom).
* **A colour swatch** with a palette and a **No colour** option. No colour
  paints nothing: polygons and frames render as hollow outlines, points as
  hollow rings — no grey stand-in, no legend.
* **A label picker (Aa)** listing the dataset's own columns under their
  data-dictionary names. The chosen attribute is written beside every feature
  on the map — settlements by name, facilities by `is_active`, anything the
  data carries. Booleans and numbers render too.

Clicking a feature opens its record in the panel: every attribute, labelled by
the dataset's data dictionary.

## The place filter

The header chip opens a State → LGA → Ward cascade built from the national
frame index. Picking a unit flies the camera to it immediately and replaces
the viewport grid with exactly that unit's frames, loading behind the moving
camera.

> [!NOTE]
>
> The filter scopes the **frame grid**, not the data layers: dataset overlays
> and choropleths still load by viewport, and area analysis always measures
> the drawn polygon as drawn — a polygon crossing the selected LGA's boundary
> includes what lies outside it. Draw inside the unit if the unit is the
> question.

## Frames and what is inside them

At zoom 8 and up the national frame grid draws over the map. Clicking a frame
opens it in the panel:

* its administrative assignment (State, LGA, Ward, Zone),
* the values every enabled baseline records on it,
* **In this frame** — every feature of the key's ordinary datasets whose
  geometry falls in the cell, each expandable in place to its full record.

```text the panel, after clicking a frame theme={null}
Frame 2163706
State   FCT
LGA     ABUJA MUNICIPAL AREA COUNCIL
Ward    WUSE

IN THIS FRAME · 1
› Medicaid Radioagnostic        Health facilities (NHFR)
    Facility level              Primary
    Ownership                   Public
    …
```

## Drawing

Drawing is first-class: a shape is whatever your product makes of it — a work
area, a site, a zone — and analysing it is just one of the actions on it.

* Shapes persist on the map and reopen on click; double-click edits points.
* A shape can be **reshaped but never dragged whole** — a slipped click cannot
  silently move a work area.
* Once anything is drawn, a **Drawings** row appears under the dataset list
  with a live count. Unchecking it hides every drawn shape (they stay in
  exports); starting a new drawing shows them again.

The drawing's screen offers **Analyse this area**, **Export drawings** and
**Delete this shape**.

## Area analysis

Analysing a drawn polygon asks the API for:

* **Totals** — area-weighted population (or any additive metric the analysis
  dataset carries), area, density, and how much of the polygon has data.
* **Amenities** — for each enabled facility-like dataset: how many features
  fall inside, and the nearest one with its distance.
* **Travel time** — with `physicalDatasetId` set: minutes to the nearest
  facility by walking, motorbike and vehicle, over slope and land cover.

The same result reaches your app through `onAnalyze`, so you can store it,
chart it, or build a report from it.

## Measuring

`Shift`-click two features — any geometry, across datasets — for the distance
between them (edge to edge and centre to centre for polygons) and road
directions where available. The measure tool on the toolbar does the same from
arbitrary points. `⌘`/`Ctrl`-click builds a multi-selection; `⌘K` opens a
command palette with every action.

## Basemaps

The toolbar's basemap button opens a picker: **dark, light, satellite,
streets, 3D** (Mapbox Standard). Switching rebuilds the grid, the filtered
frames and every enabled overlay; drawn shapes survive, and the camera stays
where the user put it.

## Export and restore

The toolbar's export button offers the whole workspace in three forms:

* **Image (PNG)** — the view with the legend, a scale bar and attribution.
* **Map (JSON)** — a restorable `MapState`: camera, basemap, place filter,
  datasets with colours and label choices, drawings and their visibility.
  Pass it back as `state` to reopen the exact view. It references datasets
  **by id only** — contents reload through the API, so licensing travels with
  the key, never with the file.
* **Drawings (GeoJSON)** — just the shapes, for QGIS, ArcGIS or your pipeline.

```ts receiving exports theme={null}
createLociMap(el, {
  // …
  onExport: (exp) => {
    if (exp.kind === "map") saveWorkspace(exp.state);  // JSON state
    if (exp.kind === "drawings") store(exp.drawings);  // GeoJSON FC
    if (exp.kind === "image") upload(exp.blob);        // PNG blob
  },
});
```

With the hosted embed, exports arrive as a cancelable `loci:export`
CustomEvent on the mount element (`event.detail` is the `MapExport`); call
`event.preventDefault()` to take it, or let it fall through to a file
download.

## The controller

`createLociMap` resolves to a controller:

```ts theme={null}
controller.map;              // the underlying mapboxgl.Map
controller.getState();       // MapState — persist it, restore with `state`
controller.getDrawings();    // GeoJSON FeatureCollection of drawn shapes
controller.exportImage();    // Promise<Blob> — the composed PNG
controller.setSidebarPosition({ x, y });
controller.destroy();
```

> [!NOTE]
>
> Analysis results are deliberately not part of `MapState`. Restoring a state
> brings back the drawings, not their numbers: analysis runs only when a user
> clicks **Analyse this area** on a shape, and then against current data under
> the opening key. Persist results from `onAnalyze` if your product needs
> yesterday's figures — for example to build a report alongside
> `exportImage()` and `getState()`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.