obsidian-maps

After setting up the Marker coordinates property in a Map view, you can use the following view options to customize the display:

• Center coordinates: Set the initial map center.
• Default zoom: Set the initial zoom level.
• Zoom limits: Define the minimum and maximum zoom levels.
• Marker icon/color: Choose specific properties to drive the icon and color of each marker.

To add the map layout to Obsidian Bases, install the Maps community plugin via the Obsidian settings interface:

1. Open Settings → Community plugins.
2. Select Browse, then search for Maps.
3. Select Install, then Enable.

To display markers on a map, use the Markers section within the Map view configuration menu (located in the top left corner of the base). Markers are driven by properties assigned directly to individual notes.

Supported properties for marker styling include:

• coordinates: Stored as latitude, longitude (e.g., 48.85837\n2.294481). You can obtain these by right-clicking a location on the map and selecting Copy coordinates.
• icon: A string representing a name from the Lucide library.
• color: A valid CSS value (e.g., hex, RGB, or named colors like red).

To show notes on a map, you must first add a coordinates property to your notes. The plugin supports both a single text property and a list property format.

Once properties are added, create a Map view in an Obsidian Base and configure the Marker coordinates option to point to your chosen property. Markers will dynamically appear and update based on the view's active filters.

# Option 1: Text property
location: 34.13956, -118.38710

# Option 2: List property
location:
  - 34.13956
  - -118.38710

Right-clicking on the map provides several context-aware actions:

• New note: Creates a new file. If a coordinates property is configured in the Map View, the new note will be pre-filled with the clicked coordinates in the format [lat, lng].
• Copy coordinates: Copies the formatted coordinates of the clicked location to the clipboard.
• Set default center point: Updates the map's center configuration to the current clicked coordinates.
• Set default zoom: Updates the map's defaultZoom configuration to the current zoom level (rounded to 1 decimal place).

Instead of using properties from the individual note, you can derive marker icons and colors from the note's assigned type. This is done using Bases formula properties.

To access properties from the first assigned type of a note, use the following formulas in the Properties configuration menu:

To get the icon from the type:

list(type)[0].asFile().properties.icon

To get the color from the type:

list(type)[0].asFile().properties.color

// Get the icon from the type
list(type)[0].asFile().properties.icon

// Get the color from the type
list(type)[0].asFile().properties.color

The obsidian-maps plugin allows you to define custom background tile sets that can be used across all maps. These are managed via the MapSettingTab in the plugin settings.

A TileSet consists of:

• name: A descriptive name for the background (e.g., 'Terrain', 'Satellite').
• lightTiles: The Tile URL or style URL used when Obsidian is in Light mode.
• darkTiles: (Optional) The Tile URL or style URL used when Obsidian is in Dark mode. If omitted, the lightTiles URL will be used as a fallback.

Example URLs provided in documentation:

• Light mode: https://tiles.openfreemap.org/styles/bright
• Dark mode: https://tiles.openfreemap.org/styles/dark

The GEOLOCATION_OPTIONS constant provides a recommended PositionOptions configuration for geolocation requests in Obsidian. It is designed to balance accuracy with battery/resource usage by allowing cached positions.

export const GEOLOCATION_OPTIONS: PositionOptions = {
	enableHighAccuracy: true,
	timeout: 10000,
	maximumAge: 5000
};

The geolocationErrorMessage(error) function converts a standard GeolocationPositionError into a human-readable string suitable for UI display. It maps the following error codes:

• error.PERMISSION_DENIED $\rightarrow$ 'Location permission denied'
• error.POSITION_UNAVAILABLE $\rightarrow$ 'Location information unavailable'
• error.TIMEOUT $\rightarrow$ 'Location request timed out'
• All other errors $\rightarrow$ 'Failed to get location'

import { geolocationErrorMessage } from 'obsidian-maps/src/map/utils';

// Assuming 'error' is a GeolocationPositionError caught from navigator.geolocation
try {
  // ... geolocation logic
} catch (error) {
  const message = geolocationErrorMessage(error);
  console.error(message);
}