Theme System
This section documents the technical structure of pitchmappr themes. It's primarily relevant for users creating custom themes in the Theme Editor (mapprstyle.html) or for developers building integrations. If you just want to use the built-in themes, Section 2.1 (Base Map Theme) and Section 10 (Built-in Themes) cover what you need.
Theme Object Properties
Every theme (built-in preset or custom) is a JavaScript object that defines how the base map should look. Themes are loaded via <script> tags or the theme manifest, registered to window.PITCHMAPPR_THEMES, and merged into AppState.settings.customThemes[] on initialization. When a theme is applied, ThemeMod.apply() processes all properties and rebuilds the map style from scratch.
Core
| Property | Type | Description |
|---|---|---|
name | string | The display name of the theme shown in dropdown menus and the theme list. Must be unique across all loaded themes. Used as the theme key when prefixed with custom:. Custom themes appear with a star (★) prefix in dropdown menus. |
base | enum | The Protomaps flavor that provides the base color palette. One of: light (warm, full-color), white (clean data-viz), grayscale (neutral mono), dark (inverted), black (high-contrast data-viz). The base flavor provides approximately 87 default color values that the overrides property can selectively replace. |
_focusTheme | boolean | Marks this theme as a focus-mode-only theme. Focus themes appear only in the Focus Theme dropdown (not the regular theme dropdown) and include focusColors for mask and border styling. When applied, they also set marker color schemes and other focus-specific defaults. |
_preset | boolean | Marks this theme as a built-in preset (loaded from the themes/*.js files shipped with pitchmappr). Preset themes cannot be edited or deleted by the user. They appear in theme lists without the star (★) prefix that custom themes receive. |
Colors
| Property | Type | Description |
|---|---|---|
overrides | object | Color overrides merged on top of the base flavor. Contains flat hex color keys (87 available, e.g. earth, water, major, boundaries, city_label) plus nested objects for pois (8 category colors) and landcover (7 terrain type colors). Only non-default values need to be specified — anything not overridden falls back to the base flavor's default. These colors directly determine every fill, stroke, and text color on the map. |
Layer Visibility
| Property | Type | Description |
|---|---|---|
layerVisibility | object | Controls which map layers are visible when the theme is applied. Processed in two passes: coarse keys first (e.g. roadLabels:false hides all road labels, shields, arrows, and addresses), then fine-grained keys override (e.g. rlabel_shields:true re-enables shields specifically). This two-pass system allows themes to broadly hide entire categories then selectively re-enable specific layers within those categories. Coarse keys: roadLabels, waterLabels, countryLabels, cityLabels, stateLabels, buildings, pois. Fine-grained keys: 19 individual layer toggles matching the controls in Section 2.2. |
Line Widths
| Property | Type | Description |
|---|---|---|
lineWidths | object | Multipliers for road and boundary line widths. Supports two formats: per-type (highways, major, minor, service, other, boundaries — each ranging from 0 to 3x) for fine-grained control, or shorthand (roads, boundaries) where roads applies uniformly to all road types. Per-type keys take priority when both formats are present. A value of 1 means default width; 0 hides roads entirely; 2 doubles the width. This is critical for finance maps where roads should be subtle (0.5–0.8x) or invisible (0). |
Label Styles
| Property | Type | Description |
|---|---|---|
labelStyles | object | Per-category label styling overrides for five label types: country, city, state, road, water. Each category supports three properties: haloWidth (0–3, controls text outline thickness), textTransform ('uppercase' or 'none', controls text case), and textSizeMultiplier (0.5–2.0, scales text size). These allow themes to style each label category independently — for example, uppercase country labels with a thick halo paired with smaller road labels with no halo. |
Typography & Language
| Property | Type | Description |
|---|---|---|
font | string | The font family applied to all base map text labels. Default is 'Noto Sans Regular' (served from the Protomaps CDN). Alternative fonts require a different glyph CDN. Does NOT affect marker labels (those use the separate labelFont setting in the Markers tab). |
glyphsUrl | enum | Selects the glyph (font file) CDN: 'protomaps' serves Noto Sans variants, 'undp' serves Open Sans and Roboto variants. Must match the font selection — using a Protomaps font name with the UNDP CDN will cause labels to fail to render. |
language | string | ISO language code for base map labels. Determines which translation of place names is shown. For example, 'en' shows "Germany", 'de' shows "Deutschland", 'ja' shows Japanese characters. 41 languages are supported. |
Advanced Rendering
| Property | Type | Description |
|---|---|---|
buildingOpacity | number | Controls the transparency of building footprint fills (0–1). At 0, buildings are invisible even when the building layer is enabled. At 1, buildings are fully opaque. Default is 0.5 (semi-transparent). Focus themes typically set this to 0 since buildings are too detailed for country-level views. |
boundaryDash | string | Controls the dash pattern for political boundary lines. Options: 'solid' (continuous line, default), 'dashed' ([6,4] pattern), 'dotted' ([1,3] pattern), 'dash-dot' ([6,3,1,3] pattern). Dashed boundaries create a softer, less definitive look compared to solid lines. |
labelScale | number | Global multiplier for ALL label text sizes (0.5–2.0). Applied after per-category textSizeMultiplier from labelStyles, so the effects stack multiplicatively. Provides a single control to uniformly scale all labels up or down without changing their relative proportions. |
poiIcons | boolean | Controls whether POI markers show category icons. When false, icon images are removed from the POI layer, showing only text labels without the category graphics (shopping bag, restaurant, etc.). Focus themes typically set this to false. |
Markers
| Property | Type | Description |
|---|---|---|
colorScheme | string | References a marker color scheme by key ('standard', 'pitchbook', 'slate', 'warm', 'slateGreyLight'). When a theme is applied, this sets the active marker color palette. Allows themes to pair with a complementary marker palette — dark themes pair well with 'slate', focus themes with 'slateGreyLight'. |
markerSettings | object | Default marker and label settings applied when the theme loads. Keys include: markerScale (size multiplier), markerBorder (white outline), markerNumbers (show indices), markerLabelSize (px), markerLabelColor (hex), markerLabelHaloSize, markerLabelHaloColor, labelPosition ('above'/'right'), labelBg ('white'/'none'). These override the user's current marker settings when the theme is first applied. |
Highway Shields
| Property | Type | Description |
|---|---|---|
shieldSettings | object | Default styling for highway route shields. Keys: textColor (hex color for route numbers), textSize (multiplier applied to base 8px), iconSize (multiplier applied to base 0.8 icon scale). Allows themes to match shield appearance to their overall visual style. |
Focus Mode Only
| Property | Type | Description |
|---|---|---|
focusColors | object | Colors for the focus mode overlay system. Keys: maskColor (background overlay), targetFillColor (focused country fill), targetBorderColor + targetBorderWidth (focused country outline), admin1BorderColor + admin1BorderWidth + admin1Dashed (internal boundaries), neighborFillColor + neighborBorderColor + neighborAdmin1BorderColor (surrounding countries). These values are applied to focus mode settings when the focus theme loads. |
focusCitySettings | object | Default city marker and label settings for focus mode. Keys: cityMarkerSize, cityMarkerColor, cityMarkerBorder, cityMarkerBorderColor, cityLabelSize, cityLabelColor, cityLabelHaloSize, cityLabelHaloColor, cityLabelPosition. Applied to focus mode city properties when the theme loads. |
PMTiles Shield Remap
The application's PMTiles basemap (130.9GB, basemap_full.pmtiles) uses a ref field for highway shield text, not shield_text as expected by Protomaps basemaps v5. The _vectorStyle() function automatically remaps all shield_text references to ref in the roads_shields layer's filter, text-field, and icon-image expressions. This remap also applies in mapprstyle.html's preview. Shield sprites (US Interstate, NL S-road, generic) are served from the Protomaps basemaps-assets CDN and match the sprite names generated by the remapped expressions. No user action is required — this is handled transparently.