API reference · SF Map SVG

Entry points

Import from the smallest entry that has what you need. Data entries export frozen objects; clone before editing.

Import from	Exports	Purpose
`@kahwee/sf-map-svg`	createMap, renderMap, getLayerPaths	The data-free root.
`/static`	renderMap, getLayerPaths	Server-safe rendering with no DOM.
`/map`	createMap	The interactive controller alone.
`/data/static`	staticMapData	Complete geography for static maps.
`/data/full`	fullMapData	Complete geography for interactive maps.
`/data`	coast, districtMaps, neighborhoodCollections, neighborhoodSources, getNeighborhood, searchNeighborhoods, catalog, …	Datasets and lookup helpers.
`/data/coast`, `/data/districts`, `/data/realtor`, `/data/sf-find`, `/data/analysis`, `/data/landmarks`, `/data/highways`, `/data/roads`, `/data/stations`, `/data/lookup`, `/data/catalog`	one dataset each	Compose your own geography.
`/geometry`	rawProject, geometryPath, positions	Projection and path helpers.
`/guide`, `/guide/map`, `/guide/data`, `/guide/static`, `/guide/detailed`	createGuideController, mountGuideController, createGuideMap, mountGuideMap, guideMapData, createGuideSVG, createGuideShell, loadGuideDetailedData	Lightweight guide presets.
`/presets`	guideOptions	Guide configuration without data.
`/transit`	createTransitAnimation	The schematic BART animation.

renderMap

renderMap(data: StaticMapInput, options?: StaticMapOptions)
  → { svg: string; project: (position) => [x, y]; viewBox: [0, 0, width, height] }

Renders a self-contained SVG string with no DOM. project converts [lng, lat] into the SVG’s coordinates.

Option	Type · default	Description
`layers`, `appearance`	StaticMapLayers, StaticMapAppearance	Shared presentation vocabulary. Grouped keys override flat keys; static appearance supports theme, colors and districtStyle. Neighborhood labels remain browser-only.
`source`	NeighborhoodSource	Select a supplied definition when using source-aware MapData (including fullMapData). SFAR is preferred by default; unavailable sources fail. Compact StaticMapData already chooses its neighborhoods.
`year`	2002 \| 2012 \| 2022 · 2022	District map year.
`theme`	'districts' \| 'transit' · 'districts'	Soft district palette or quiet transit palette.
`width`, `height`	number · 800	SVG size and view box.
`padding`	number · 28	Space around the fitted city.
`districtFills`	boolean · true	Colored district areas.
`districtLines`	boolean · true	District outlines.
`districtLabels`	boolean · true	District number badges.
`districtStyle`	(district) => { fill?, stroke?, opacity? }	Per-district style, evaluated once per district.
`neighborhoodLines`	boolean · false	Dashed outlines of `data.neighborhoods` (SFAR in the presets).
`landmarks`	boolean · false	Park boundaries and names.
`highways`	boolean · false	Highway lines.
`keyRoads`	boolean · false	Selected road corridors.
`roadLabels`	boolean · same as keyRoads	Road names.
`bartStations`	boolean · false	The eight BART stations in the city.
`labels`	boolean · true	Hide every visible label while keeping titles.
`markers`	readonly MapMarker[] · []	Points drawn above everything else.
`overlays`	readonly MapOverlay[] · []	Your own lines and polygons.
`colors`	Partial<Record<ColorKey, string>>	water, land, district, neighborhood, highway, road, park, landmark, bart, label, marker, selected.
`animation`	boolean \| { duration?, delay? } · false	Self-contained draw-in. `duration` defaults to 2400 ms and scales the sequence.
`title`	string · 'San Francisco map'	Accessible title.
`idPrefix`	string · generated	Prefix for element ids and animation scope.

getLayerPaths

getLayerPaths(data: StaticMapInput, options?: StaticMapOptions)
  → { year, viewBox, project, coast, districts, neighborhoods, highways,
      landmarks, keyRoads, bartStations }

Returns fitted path strings and points for each layer without building SVG markup, for canvas renderers and custom drawings.

createMap

createMap(data: MapData, options?: MapOptions) → MapController

Creates an interactive map. Mount controller.element. Unknown options throw, so typos surface immediately.

Option	Type · default	Description
`mode`	'basemap' \| 'neighborhoods' \| 'districts' · 'basemap'	What the map is about; sets default layers and selection.
`source`	'realtor' \| 'sf-find' \| 'analysis' · 'realtor'	Neighborhood definition.
`neighborhood`	string	Select a neighborhood by name or alias at start.
`year`	2002 \| 2012 \| 2022 · 2022	District map year.
`labels`	boolean · true	Visible labels.
`layers`	InteractiveLayers	See layers.
`controls`	MapControls	See controls.
`features`	MapFeatures	See features.
`appearance`	MapAppearance	See appearance. Update live with configure.
`markers`	readonly MapMarker[]	Initial markers.
`overlays`	readonly MapOverlay[]	Initial overlays.
`legend`	{ builtins?, hidden?, items? }	Legend entries.
`strings`	Partial<Record<StringKey, string>>	Replace interface text for translation.
`attribution`	'full' \| 'compact' · 'full'	Source credit style.
`fitPadding`	number \| MapPadding · 24	Screen pixels kept clear when fitting.
`selectableNeighborhoods`	boolean · true	Whether neighborhoods respond to selection.

features

Opt-in behaviors. Pass true for defaults or an object to tune them. Change them at runtime with map.configure({ features }). Reduced motion always takes precedence.

Feature	Options · defaults	Description
`motion`	{ duration: 320 }	Ease the camera.
`markerEntrance`	{ duration: 420, stagger: 35 }	Animate new markers in.
`selectedMarkerRing`	{ color, width: 2, gap: 3 }	Ring around the selected marker.
`clustering`	{ radius: 32 }	Screen-space marker clusters with an accessible chooser.
`layerTransitions`	{ duration: 360 }	Fade layer switches; crossfade `setSource` and `setDistrictStyle`.
`districtMorph`	{ duration: 1100 }	Morph outlines on `setDistrictYear`.
`northArrow`	boolean	Show a north arrow.
`scaleBar`	boolean	Show an approximate scale bar.

layers

Each key is a boolean override. Omitted keys follow the mode: district layers show in 'districts', neighborhood layers in 'neighborhoods', and the rest show in every mode.

Key	Default	Draws
`districtFills`, `districtLines`, `districtLabels`	districts mode	District areas, outlines and numbers.
`neighborhoodLines`, `neighborhoodLabels`	neighborhoods mode	Neighborhood outlines and names.
`landmarks`	on	Parks.
`highways`, `keyRoads`, `roadLabels`	on	Roads and their names.
`bartStations`	on	BART stations.

controls

Independent switches for the map’s own interface: zoom, pan, reset, labels, touch, legend, neighborhoodPicker, markerPicker, help and status. Hiding a picker means you should provide your own accessible list. Attribution always remains.

appearance

Update with map.configure({ appearance }) while preserving camera, selection and focus. Token objects merge by key; appearance: undefined resets the group.

Key	Type · default	Description
`theme`	'districts' \| 'transit' · 'transit'	Base palette.
`colors`	Partial<Record<ColorKey, string>>	As in renderMap.
`districtStyle`	(district) => DistrictStyle	Initial choropleth; change with `setDistrictStyle`.
`labelStyle`	{ fontFamily?, fontWeight?, haloColor? }	Label typography.
`labelSize`	{ min?: 11, max?: 12 }	Screen-pixel label sizes, 8 to 32.
`areaStyle`	{ selectedFill?, selectedStroke?, hoverFill?, hoverStroke? }	Neighborhood highlight colors.
`style`	{ ink?, surface?, accent?, border?, focus?, controlGap?, font? }	Tokens for the map’s controls. CSS variables work.
`markerRadius`, `markerHitSize`	number · 6, 44	Marker size and touch target, in screen pixels.
`markerColor`, `selectedMarkerColor`	string	Marker colors.

MapController

Member	Signature	Description
`element`	HTMLElement	Mount this.
`overlayElement`	HTMLDivElement	Positioned layer for your own HTML.
`camera`	MapCamera	See MapCamera.
`destroyed`	boolean	True after `destroy()`.
`configure`	(patch: { features?, layers?, controls?, appearance?, mode?, source?, year?, labels? })	Atomic runtime change; invalid patches change nothing. Omitted keys retain values; undefined groups reset.
`getConfiguration`	() → snapshot	Current mode/source/year/labels plus detached presentation overrides. Camera and selection are separate. Styling callbacks keep their identity.
`getResolvedConfiguration`	() → ResolvedMapConfiguration	Current mode/source/year/labels and effective layer switches; label collision and zoom rules still apply.
`getCapabilities`	() → MapCapabilities	Supplied sources, years and layer data availability, independent of visibility.
`selectFeature`	(reference, options?) → boolean	Typed kind/ID with neighborhood source or district year. Select only in current geography; mismatches return false without switching. A null ID clears that kind.
`on`	(type, listener) → unsubscribe	Typed events; see Events.
`setMode`	(mode, options?)	Switch mode; by default reset the camera. Pass `{ resetView: false }` to preserve the camera. Setters share the atomic configuration path.
`setSource`	(source, options?)	Switch neighborhood definition; by default reset the camera. Pass `{ resetView: false }` to preserve the camera. Setters share the atomic configuration path.
`setDistrictYear`	(year, { animate?, duration? })	Switch district map; morphs with `districtMorph`.
`setDistrictStyle`	(style \| undefined)	Restyle districts.
`setLabels`	(visible: boolean)	Show or hide labels.
`setMarkers`, `setOverlays`	(items)	Replace items; markers reconcile by stable id.
`selectMarker`, `selectNeighborhood`, `selectDistrict`	(id \| name \| null, { fit?, animate?, duration? }) → boolean	Select, optionally fitting the camera.
`getSelectedMarker`, `getSelectedNeighborhood`, `getSelectedDistrict`	() → selection \| null	Detached copies of the current selection.
`setTouchNavigation`	(enabled: boolean)	Engage map touch gestures.
`projectToScreen`	(lng, lat) → { x, y, visible }	Screen position of a point.
`destroy`	()	Idempotent; releases observers, listeners and animations. Does not remove host-owned DOM; other calls after destruction throw.

MapCamera

Viewports are [x, y, size] in the map’s fixed 800 × 800 projected space. Movement methods take { animate?, duration? }; get() and stop() take no arguments.

Method	Signature	Description
`get`	() → MapViewport	Current viewport.
`set`	(view, options)	Move to a viewport.
`fit`	(geometry, { padding?, … })	Fit any GeoJSON geometry.
`pan`	(x, y, options)	Pan by projected units.
`zoom`	(factor, options)	Zoom about the center.
`reset`	(options)	Return to the whole city.
`stop`	()	Stop camera motion where it is.

Events

Subscribing

const unsubscribe = map.on('neighborhoodchange', ({ name, source }) => {
  console.log(name, source);
});

Event	Detail	When
`selectionchange`	{ kind, current, previous }	Common detached envelope for marker, neighborhood and district selection; null clears. Existing change events retain their payloads.
`districtchange`	{ id, year, district }	District selection changes.
`districthover`	{ id, year, district }	The hovered district changes.
`districtactivate`	{ id, year, district }	A district is clicked or activated by keyboard.
`districtyearchange`	{ year, previousYear }	The district map year changes.
`neighborhoodchange`	{ id, name, source, feature }	Neighborhood selection changes.
`markerchange`	{ id, marker }	Marker selection changes.
`overlayactivate`	{ overlay }	An overlay is activated.
`clusteractivate`	{ markers }	A marker cluster is activated.
`viewportchange`	{ viewport }	The camera moves.
`mapresize`	undefined	The map’s size changes.

Types

TypeScript

interface MapMarker {
  id: string;
  lng: number;
  lat: number;
  label?: string;
  selected?: boolean;
  color?: string;
  radius?: number; // screen pixels (interactive), SVG units (static)
}

interface MapOverlay {
  id: string;
  geometry: LineString | MultiLineString | Polygon | MultiPolygon;
  stroke?: string;
  strokeWidth?: number;
  fill?: string;
  fillOpacity?: number;
  visible?: boolean;
  label?: string;
}

interface DistrictStyle {
  fill?: string;
  stroke?: string;
  opacity?: number;
}

type MapViewport = readonly [x: number, y: number, size: number];
type DistrictYear = 2002 | 2012 | 2022;
type NeighborhoodSource = 'realtor' | 'sf-find' | 'analysis';

Guide and transit

createGuideController(options?: MapOptions) → MapController
mountGuideController(shell: HTMLElement, options?: MapOptions) → MapController
createGuideSVG(options?: StaticMapOptions) → { svg, project, viewBox }
createGuideShell(options?: StaticMapOptions) → string
createTransitAnimation() → TransitAnimationElement

The guide entries wrap createMap with the lightweight guide geography and layout, and can progressively enhance a server-rendered shell. The transit entry returns a paused, keyboard-operable schematic BART animation; call destroy() when you remove it.