<mosaica-map>

An interactive map with no panels around it.

Use the map on its own when you lay out your own panels around it. It draws one view's points, density and annotation layers. When the viewer picks a point or draws a region, the map records it in the store, so the other elements on the page follow.

The map takes its store from its store property or from an enclosing <mosaica-store>. It can also build its own from viewer-url and token or authorise.

When the map first gets a store, it frames the items the filters match unless the camera has already been moved. It frames them again when the view switches to one with a different extent, but a change of filter leaves the camera where it is.

A box or lasso drawn with the toolbar becomes the store's selected region, which narrows the map and every count to the items inside it. Shift-drag draws a box without changing tool. With the map focused, the arrow keys pan and + and - zoom. Escape cancels a shape being drawn, or clears the region when there is no shape, or drops the picked item when there is neither.

When the map cannot draw the view, it says why over the canvas.

The canvas is a single tab stop, and it takes any tabindex or aria-label you set on the map. Without an aria-label, the canvas is labelled with its keys, "map: arrow keys pan, + and - zoom", so that someone using a screen reader knows how to move it.

import '@mosaicajs/components/map';

Attributes

Attribute	Property	Type	Default	Description
tabindex
aria-label
colour-by	colourBy	string	''	What colours the points: a rendered column (one sent with the points), cluster:<layer> for a layer that can colour, or none for a single colour. Unset, the store's choice stands.
layers	layers	string[] | null	null	The annotation layers to draw, separated by spaces or commas. Each also draws the layers it depends on. Unset, the store's choice stands.
budget	budget	number	0	How many marks to aim for on screen. 0 keeps the store's budget, which starts at 250000.
cluster-budget	clusterBudget	number	0	The most clusters a nested or dag layer is cut to (Store.setClusterBudget). 0 keeps the store's setting; setting 0 after another value removes the limit, giving the finest cut.
tooltip-fields	tooltipFields	string	''	The columns the hover tooltip shows under the point's title, separated by spaces or commas. Only rendered columns arrive with the points, so another column shows nothing.
title-field	titleField	string	''	The field that titles a point in the hover tooltip. A rendered column shows at once; any other field is read from the item's record once the pointer rests on the point. Unset, the title is the point's mosaica_id.
mode	mode	'pan' | 'box' | 'lasso'	'pan'	What a drag does: pan moves the camera, box draws a box selection and lasso a freehand one.
palette	palette	PaletteName | ''	''	The palette clusters are coloured from when the points are coloured by a layer: okabe-ito, tableau10, tableau20 or kelly. It is set on the store (Store.setPalette). Unset, the store's palette stands, which starts as tableau10.
cluster-level	clusterLevel	number | null	null	The level of a stacked or tiered layer at which clusters are coloured, labelled and outlined. Unset, the coarsest level. A nested or dag layer ignores it.
basemap	basemap	BasemapChoice | null	null	What is drawn under the points. world is the server's outline of land, coastlines and country borders, and needs a view with a map projection. {tiles, attribution} is a tile server's URL template with {z}, {x} and {y} and the credit to show, and needs a view with a tileScheme. {image, bounds} is one image over [x0, y0, x1, y1] in the view's coordinates (degrees on a geographic view), or over the whole frame without bounds. You can also pass none, a deck.gl layer you built in the map's 512-unit world, or an object mapping view ids to any of these for a different basemap per view. The attribute takes only world and none. Unset, a view with a map projection gets world and any other view gets nothing. A value that does not fit the view is shown as an error over the map; one that stops fitting after a switch of view draws nothing, and a note says why. The points are drawn either way.
ground	ground	'light' | 'dark' | ''	''	Whether the map's background is light or dark, for when it differs from the page's, such as a light basemap on a dark page. Labels and density colours follow it; the toolbar and panels follow the page. Unset, it follows the page's color-scheme.
no-points	noPoints	boolean	false	Hides the points. Density, outlines, labels and the selection are still drawn.
point-opacity	pointOpacity	number | null	null	A fixed point opacity from 0.1 to 1. Unset, points get more transparent the more of them are drawn.
density	density	DensityMode	'none'	How density is drawn under the points: none, smooth (a soft wash), hex (hexagons), grid (square cells) or contours (lines of equal density). Density is counted by the server over every matching item, so it covers more than the sampled points drawn. It counts the highlighted items if there is a highlight, otherwise the items the filters and selection match.
density-resolution	densityResolution		DEFAULT_DENSITY_CELL_PX	The size of density's cells on screen, in CSS pixels: 32, 24, 16, 12, 8, 6 or 4. Other values are rounded to the nearest of these. If the server's selection.maxAggregateCells does not allow that many cells, the finest size that fits is drawn; densityStops() says which sizes fit.
density-colours	densityColours	DensityColours | ''	''	The colours density is drawn in: warm-grey, viridis, cividis, magma or greys. Unset, a smooth wash under the points is warm grey and anything else is viridis.
density-strength	densityStrength	number	1	How strongly density is drawn, from 0.1 to 1.
density-scale	densityScale	DensityScale	DEFAULT_DENSITY_SCALE	How a cell's count maps to a colour, from zero to the densest cell in and around the view: linear, or log on log(1 + count). log is the default because counts are skewed on most maps, and on a linear scale only the densest few cells stand out. Any other value is taken as log.
category-palette	categoryPalette	CategoryPaletteName | ''	''	The palette for colouring by a category column: tableau10, okabe-ito, set2 or dark2. Unset, the current choice stands, which starts as tableau10.
ramp	ramp	RampName | ''	''	The colour ramp for colouring by a number column: viridis, cividis, magma, greys or red-blue. Unset, the current choice stands, which starts as viridis.
ramp-scale	rampScale	RampScale | ''	''	How numbers are placed on the ramp, linear or log. Unset, the current choice stands.
ramp-reverse	rampReverse	boolean	false	Runs the ramp from its high end to its low end.
radius	radius	number | null	null	A fixed point radius in pixels. Unset, the radius depends on how many points are drawn and on the zoom. Ignored while size-by names a column.
size-by	sizeBy	string	''	The rendered number column that sizes the points, or none for a single size. Each value is placed between size-min and size-max on size-scale, against the range of the values drawn. A point with no value, NaN or an infinity is drawn as a ring. Unset, the store's choice stands.
size-min	sizeMin	number | null	null	The radius in pixels of the smallest value under size-by. A value that is not above zero is ignored. Unset, the current choice stands, which starts at 2.
size-max	sizeMax	number | null	null	The radius in pixels of the largest value under size-by. A value that is not above zero is ignored. Unset, the current choice stands, which starts at 9.
size-scale	sizeScale	SizeScale | ''	''	How values are placed between the two sizes: linear, log, or rank among a sample of the values drawn. Unset, the current choice stands, which starts as linear.
no-controls	noControls	boolean	false	Hides the toolbar.
controls-corner	controlsCorner	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'	'top-left'	The corner the toolbar sits in: top-left, top-right, bottom-left or bottom-right. Content in the same corner's slot sits below the toolbar in a top corner, and above it in a bottom corner.
viewer-url	viewerUrl	string	''	The base URL of the Mosaica viewer server, for the store the element builds: a full URL such as https://maps.example.org, or a path such as /mosaica. Unset, the page's own origin. Read only by the map, the explorer and <mosaica-store>. Changing it builds a new store.
token	token	string	''	A viewer token for the store the element builds. Without token or authorise, only an open server (serve.open) answers. Read only by the map, the explorer and <mosaica-store>. Changing it builds a new store.
artifacts-per-tile	artifactsPerTile	number | null	null	The most artifacts one level of a layer shows per map tile, for the store the element builds. Unset, 50, or the server's selection.max_artifacts_per_tile if lower. A value above that maximum is refused. Read only by the map, the explorer and <mosaica-store>. Changing it builds a new store.

Properties

Set as JavaScript properties; they have no attribute.

Property	Type	Default	Description
valueColours	Colouring['values'] | null	null	Colours for individual category values, by column and category key, as #rrggbb, such as {field: {'cs.CV': '#f28e2b'}}. Setting it replaces every value colour chosen before, including those chosen on a field card. Use it to restore choices you saved from mosaica-valuecolour.
clusterColours	Record<string, Record<string, string>> | null	null	Colours for individual clusters, by layer and mosaica_id (as a decimal string), as #rrggbb, such as {topics: {'4021': '#f28e2b'}}. They replace the palette colours (Store.setArtifactColours). Setting it replaces every cluster colour chosen before, including those chosen on a field card or in Edit colours. Use it to restore choices you saved from mosaica-clustercolour. Invalid entries are skipped.
lastPick	PickOutcome	null	What the last click found if it found no item: {kind: 'miss'}, or {kind: 'broken', ...} with details of a fault in the layer. null after a hit. Pass it to <mosaica-item-card>'s pick.
pickedAt	{kind: 'item' | 'artifact'; id: bigint; world: [number, number]} | null	null	What the last click picked, an item or an artifact, and where in world coordinates: the point's position, or where the click landed on an artifact. null before a pick, after a miss and after a switch of view. Pass world to screenOf() to place a card beside it.
drawnGround	'light' | 'dark'	read-only	Whether the map is drawn on a light or dark background now: ground if set, else the page's scheme.
zoom	number	read-only	The camera's zoom: 0 when the 512-unit world is 512 pixels wide, and 1 more per doubling.
store	Store | null	null	The store to use, ahead of one from context or one the element would build. The element never disposes it.
authorise	TokenSupplier | null	null	A function that returns a viewer token, used instead of token and called again before the token expires. A different function builds a new store, so keep it stable across renders. Set it together with viewer-url: a store built from viewer-url alone first sends a request with no token, and is replaced when authorise arrives.
activeStore	Store | null	read-only	The store this element is using, or null if it has none.
source	StoreSource	read-only	Where activeStore came from.

Methods

Method	Returns	Description
densityStops()	ResolutionStop[]	The density cell sizes density-resolution offers at the current camera, each with whether the server's selection.maxAggregateCells allows it. Every size is allowed before meta has loaded.
dispose()	void	Dispose of the store this map built and release its GPU resources now.
focus(options?: FocusOptions)	void	Focus the canvas, which takes the map's keys.
clearPick()	void	Drop the picked item or artifact and the ring around it, and clear the store's selection, which closes its card. A click on an empty part of the map does the same. A selected region stays.
select(shape: SelectionShape | null)	void	Select a shape in data coordinates, as drawing a box or lasso does; null clears the selection. Fires mosaica-selectchange.
screenOf(world: readonly [number, number])	[number, number]	Convert a world position to pixels from the map's top-left corner, under the current camera. A position off the map falls outside [0, width] × [0, height].
fit()	Promise<void>	Move the camera to frame every item the filters and selected region match, filling 92% of the map. If nothing matches, or the server refuses, it frames the whole extent. The camera moves when the server answers, unless it is moved first. Resolves when the camera has moved or the move was cancelled.
lookAt(x: number, y: number)	boolean	Centre the camera on a point in data coordinates, keeping the zoom. Returns false before meta has loaded.
fitTo(artifactId: bigint)	boolean	Fit the camera to an artifact's bounding box. Returns false if the artifact is not among those currently drawn (artifacts.served) or has no box.
fitBbox(extent: [number, number, number, number], fill: unknown)	boolean	Fit the camera to a box [x0, y0, x1, y1] in data coordinates, as mosaica-viewchange reports them. The canvas keeps its aspect ratio, so the area shown contains the box. fill is the share of the map the box fills along its tighter side, about 81% by default; pass 1 to restore a camera from a box mosaica-viewchange reported. Returns false before meta has loaded.

Events

Each bubbles and is composed. Events gives each detail.

Event	Fired when
mosaica-viewchange	The camera moved.
mosaica-basemapchange	The basemap's refusal or note appeared, changed or went.
mosaica-pick	A point was clicked.
mosaica-itemopen	The selected item's record arrived, however the item was selected.
mosaica-miss	A click found no point and no artifact. The map has already dropped the picked item.
mosaica-hover	The pointer moved onto or over a point.
mosaica-artifactopen	An artifact was opened and its details arrived.
mosaica-selectchange	A selection was drawn or cleared (status loading or cleared), and again when its counts arrive.
mosaica-layerchange	The layers attribute changed.

Slots

Slot	Description
top-left	Content in the top-left corner, below the toolbar when it is there.
top-right	Content in the top-right corner, below the toolbar when it is there.
bottom-left	Content in the bottom-left corner, above the toolbar when it is there.
bottom-right	Content in the bottom-right corner, above the toolbar when it is there.
tooltip	Replaces the hover tooltip's content.

Parts

Styled from outside the element with ::part().

Part	Description
canvas	The deck.gl canvas's container.
overlay	The message over the canvas when the view is refused, expired or empty, or the server cannot be reached, did not answer or is too busy. If the viewer may see no item in the view at all, it says so instead of "Nothing in view".
state	The state line inside the overlay, with data-state, and data-visible="none" if the viewer may see no item in the view.
retry	The Retry button in the overlay, after a refusal, no answer or a busy server.
refusal	The words "View refused", or "Server busy", inside the overlay, with data-code set to the refusal's code.
reason	The server's reason for a refusal, as it sent it, on a line under "View refused".
controls	The toolbar.
region-tag	The tag on the selected region's top-left corner, with how many items match inside it (or outside it, for its complement) and a button that clears it.
tooltip	The hover tooltip.
density-key	The key to density's colours in items per cell, in the bottom-left corner. Shown while density is drawn in a colour ramp or without the points.
note	Why no basemap is drawn under this view, in the bottom-right corner.
attribution	The tile server's credit, in the bottom-right corner while tiles are drawn.

CSS custom properties

Property	Default	Description
--mosaica-map-height	420px	The map's height.
--mosaica-map-bg	#f6f6f4 (light), #111317 (dark)	The canvas's background, behind the points and any basemap.
--mosaica-map-inset-left	0px	Extra space to the left of the top-left corner's content, to clear a panel you float over the map's left side. Defaults to 0.

The theme tokens apply to this element.