Map

A generic, interactive geographic map. Choose a map variant, shade individual regions, attach custom tooltips, and react to hover and click events. The USA, World, Canada, and Europe variants ship today; additional variants add their own geography under the same API. An optional legend renders below the map.

Demo

USA

The default map variant, set with mapvariant="USA", for a state-level map. Regions are keyed by USPS state abbreviation codes; unlike the other variants, state names are read directly from the underlying topology rather than localized.

View region codes

Code	Name

World

Set mapvariant="World" for a country-level map. Regions are keyed by ISO 3166-1 alpha-2 country codes, and country names are localized the same way the map's own accessible label is.

Three territories with no official ISO 3166-1 alpha-2 code — Northern Cyprus, Somaliland, and Kosovo — render in the base map at reduced opacity rather than being omitted, and are keyed by a slug (n-cyprus, somaliland, kosovo) instead of a code. Match them via regions[].name (e.g. { name: "Kosovo", fill: "..." }) the same way you would any other region by name.

View region codes

Code	Name

Canada

Set mapvariant="Canada" for a province/territory-level map. Regions are keyed by ISO 3166-2:CA subdivision codes, and province/territory names are localized the same way the map's own accessible label is.

View region codes

Code	Name

Europe

Set mapvariant="Europe" for a country-level map scoped to Europe. Regions are keyed by ISO 3166-1 alpha-2 country codes (reusing the World variant's topology and localized country names), and country names are localized the same way the map's own accessible label is.

View region codes

Code	Name

Legend

Pass legend to render a swatch + label row below the map. x-map does not auto-assign colors — supply one per entry. See Choosing legend colors below for the sequential/categorical/colorblind-safe guidance. A disclaimer caption always renders below the map, whether or not a legend is set.

Labels

Set showlabels to label each region listed in regions with its code. Regions too small to hold a label, such as the New England states, get a tethered label beside the map. Labels are white, or dark on regions left at the default fill; set regions[].labelColor for other light fills. Labels are available on the USA map only.

const labelsMap = document.getElementById("demo-labels-map"); labelsMap.regions = [ { code: "CA", fill: "var(--color-red-medium)" }, { code: "WA", fill: "var(--color-gray-darkest)" }, { code: "CO", fill: "var(--color-gray-darkest)" }, ...["AZ", "TX", "MN", "IL", "OH", "GA", "NY", "MA", "NJ"].map(code => ({ code, fill: "var(--color-blue-dark)" })), ];

Every region listed in regions is labeled, so listing all of them labels the whole map.

const labelsAllMap = document.getElementById("demo-labels-all-map"); labelsAllMap.regions = [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", ].map(code => ({ code, fill: "var(--color-blue-dark)" }));

Empty state

Set empty to overlay a message on the map, such as when no region needs attention. The map itself is unchanged. Override the message with the xMap.emptyMessage i18n key.

Non-interactive

Set interactive="false" and showtooltips="false" for a purely presentational map.

document.getElementById("static-map").regions = [ { code: "OR", fill: "var(--color-green-medium)" }, { code: "NV", fill: "var(--color-blue-medium)" }, { code: "AZ", fill: "var(--color-yellow-dark)" }, ];

API

Tag

Name	Description
`<x-map>`	Custom HTML tag.

Attributes

Name	Value	Description
`mapvariant`	String	Which map to render. Each variant ships its own geography. Today `USA`, `World`, `Canada`, and `Europe` are available. Default: `USA`
`regions`	JSON array of region objects. See Guidelines below.	Per-region configuration. Accepts an array (via property) or a JSON string (via attribute). Default: `[]`
`defaultfill`	String	Fill applied to regions without an explicit `fill` or `className`. Accepts any CSS color. Default: `var(--color-border-default)`
`strokecolor`	String	Color of the borders drawn between regions. Accepts any CSS color. Default: `var(--color-surface-canvas)`
`strokewidth`	Number or String	Width of the borders drawn between regions. Default: `1`
`interactive`	Boolean	When `false`, regions are not hoverable, focusable, or clickable and emit no interaction events. Default: `true`
`listedonly`	Boolean	When `true`, only regions listed in `regions` are interactive; the rest are not hoverable, focusable, or clickable. Default: `false`
`showtooltips`	Boolean	When `false`, the built-in tooltip is suppressed. Consumers can still react to hover events. Default: `true`
`allowhtmltooltips`	Boolean	When `true`, per-region `tooltip` strings are rendered as HTML rather than plain text. Default: `false`
`showlabels`	Boolean	When `true`, each region listed in `regions` is labeled with its code. Small regions get a tethered label beside the map. `USA` map only. Default: `false`
`empty`	Boolean	When `true`, overlays a message on the map. Override its text with the `xMap.emptyMessage` i18n key. Default: `false`
`legend`	JSON array of legend entries. See Choosing legend colors below.	Legend entries rendered as a swatch + label row below the map, whenever non-empty. Accepts an array (via property) or a JSON string (via attribute). Default: `[]`
`i18n`	string	A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Properties

Name	Value	Description
`mapVariant`	`XMapVariant` (`'USA' \| 'World' \| 'Canada' \| 'Europe'`)	Which map to render. Defaults to `USA`.
`regions`	`XMapRegionData[]` or JSON string	Per-region configuration. Recommended way to pass data, since it accepts a live array. See Guidelines.
`defaultFill`	String	Fill applied to regions without an explicit `fill` or `className`. Accepts any CSS color.
`strokeColor`	String	Color of the borders drawn between regions.
`strokeWidth`	Number or String	Width of the borders drawn between regions.
`interactive`	Boolean	When `false`, regions are not hoverable, focusable, or clickable.
`listedOnly`	Boolean	When `true`, only regions listed in `regions` are interactive.
`showTooltips`	Boolean	When `false`, the built-in tooltip is suppressed.
`allowHtmlTooltips`	Boolean	When `true`, per-region `tooltip` strings are rendered as HTML.
`showLabels`	Boolean	When `true`, each region listed in `regions` is labeled with its code. `USA` map only.
`empty`	Boolean	When `true`, overlays a message on the map. Override its text with the `xMap.emptyMessage` i18n key.
`legend`	`XMapLegendItem[]` or JSON string	Legend entries rendered below the map whenever non-empty. See Choosing legend colors.
`i18n`	object	A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Events

Name	Detail	Description
`s-mapregionclick`	`XMapRegionEventDetail`	Fires when an interactive region is clicked or activated via keyboard (Enter/Space).
`s-mapregionhover`	`XMapRegionEventDetail`	Fires when the pointer enters an interactive region.
`s-mapregionleave`	`XMapRegionEventDetail`	Fires when the pointer leaves an interactive region.

Demo

API

Tag

Name
`<XMap>`

Props

Name	Value	Description
`mapVariant`	`XMapVariant` (`'USA' \| 'World' \| 'Canada' \| 'Europe'`)	Which map to render. Defaults to `USA`.
`regions`	`XMapRegionData[]`	Per-region configuration. See Guidelines.
`defaultFill`	String	Fill applied to regions without an explicit `fill` or `className`.
`strokeColor`	String	Color of the borders drawn between regions.
`interactive`	Boolean	When `false`, regions are not hoverable, focusable, or clickable.
`allowHtmlTooltips`	Boolean	When `true`, per-region `tooltip` strings are rendered as HTML.
`showLabels`	Boolean	When `true`, each region listed in `regions` is labeled with its code. `USA` map only.
`empty`	Boolean	When `true`, overlays a message on the map. Override its text with the `xMap.emptyMessage` i18n key.
`legend`	`XMapLegendItem[]`	Legend entries rendered below the map whenever non-empty. See Choosing legend colors.
`onS-mapregionclick`	Function	Fires when an interactive region is clicked or activated via keyboard. The region details are available on `e.detail`.
`onS-mapregionhover`	Function	Fires when the pointer enters an interactive region.
`onS-mapregionleave`	Function	Fires when the pointer leaves an interactive region.

Skylab React links

General information about using our React package

Typescript

Exported types

// Supported map variants. New maps add a key here. export type XMapVariant = 'USA' | 'World' | 'Canada' | 'Europe'; // Per-region configuration entry export interface XMapRegionData { code?: string; // Region code as defined by the variant, e.g. "CA" for USA (case-insensitive). Preferred over name. name?: string; // Full region name, e.g. "California" (case-insensitive). fill?: string; // Any CSS color, including custom properties. className?: string; // Extra class(es) applied to the region's path. value?: number | string; // Arbitrary value passed back in events. label?: string; // Short, human-readable label. Defaults to the region name. tooltip?: string; // Tooltip content. HTML when allowhtmltooltips is set. disabled?: boolean; // Render but do not hover/focus/click. labelColor?: string; // Label color when showlabels is set. Defaults to white; ignored for tethered labels. } // Detail payload emitted with interaction events export interface XMapRegionEventDetail { code: string; name: string; value?: number | string; data?: XMapRegionData; } // One legend entry: a color swatch paired with a label. The consumer supplies the color. export interface XMapLegendItem { color: string; // Any CSS color, including custom properties. label: string; }

Guidelines

Choosing a map

Use the mapvariant attribute to select which geography renders. The component ships with USA, World, Canada, and Europe variants today; each new variant adds its own topology and is selected by the same prop. Shading and tooltips work identically across variants — only the set of region code/name keys changes per map. An unknown variant falls back to USA.

Setting region data

Provide a regions array (or stringified JSON) where each entry targets one region by code (preferred) or full name. Regions you do not list fall back to defaultfill.

fill — any CSS color, including design-system custom properties such as var(--color-blue-medium).
className — apply a class to the region's path to drive its fill from CSS instead of fill.
tooltip — tooltip content. Plain text by default; set allowhtmltooltips to render rich HTML.
value — arbitrary data echoed back in interaction events, useful for wiring custom UI.
disabled — render the region but exclude it from hover, focus, and click handling.
labelColor — color of the region's label when showlabels is set. Use a dark color on light fills.

Choosing legend colors

x-map renders whatever color each legend entry supplies — it does not assign colors itself. Pick a set from chart-css-utils.ts, the same source every other Skylab chart reads from, so map legends stay consistent with bar, donut, and line-chart legends:

Up to 5 colors that represent ordered steps of one measure — use the sequential set (sequentialPalette(count)), anchored on --gradient-teal-medium and grown outward (dark→light). A stacked/ranked view is a good fit.
More than 5 colors, or colors that label unrelated categories rather than ordered steps — use the categorical set (CATEGORICAL_PALETTE): teal-medium → blue-dark → purple-dark → gold-medium → blue-medium → teal-lightest → purple-light → gold-light.
Verify the chosen set against deuteranopia and protanopia (red-green color blindness) before shipping, since adjacent categorical slots can read as the same hue under those conditions. Do not rely on hue alone to distinguish regions — pair the legend with the label text, which is always visible regardless of color perception.

See Charts, gauges, KPIs in the token system docs for the full palette and legend spec.

Accessibility

The map renders as an <svg role="img"> with an accessible label (overridable via aria-label). Interactive regions expose role="button", are focusable, and can be activated with the keyboard. Provide meaningful label values for screen-reader users.

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com