useDocyrusMapView

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-map-view

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query react-leaflet leaflet @vis.gl/react-google-maps

This hook is distributed as source. It expects an authenticated Docyrus client, a QueryClientProvider, and a data source that includes at least one field-locationSelect field.

Overview

useDocyrusMapView is the map-first companion to useDocyrusDataGrid:

• loads the active Docyrus data source metadata
• auto-detects the first field-locationSelect field, or uses the slug you provide
• keeps saved-view filtering, sorting, and search wiring from useDocyrusDataGrid
• appends required map columns (id, location, title, popup fields) even when a saved view hides them
• transforms records into provider-agnostic marker objects
• returns ready-to-render helpers for both Leaflet and Google Maps

The hook is designed for pages where records stay in Docyrus, but the primary surface is a map instead of a table.

Supported map providers

1. Leaflet

Use DocyrusLeafletMapView when you want the built-in Docyrus UI map stack:

• no API key requirement
• theme-aware tile layers
• clustering
• custom Docyrus map controls (zoom, fullscreen, locate)

2. Google Maps

Use DocyrusGoogleMapView when you want Google basemaps.

Provide the key either with the hook/component googleMapsApiKey prop or through VITE_GOOGLE_MAPS_API_KEY.

Usage

Leaflet page

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import {
  DocyrusLeafletMapView,
  useDocyrusMapView
} from '@docyrus/ui/library/hooks/use-docyrus-map-view';

import { useBaseOrganizationCollection } from '@/db/collections/base-organization.collection';

export function OrganizationLocationsPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const collection = useBaseOrganizationCollection();

  const mapView = useDocyrusMapView({
    client,
    appSlug: 'base',
    dataSourceSlug: 'organization',
    collection,
    locationFieldSlug: 'map_location',
    titleFieldSlug: 'name',
    descriptionFieldSlugs: ['address', 'city'],
    searchPlaceholder: 'Search organizations',
    enableGroupMenu: false,
    enableDisplayMenu: false,
    enableRowHeightMenu: false
  });

  return (
    <div className="space-y-4">
      {mapView.toolbar}

      <DocyrusLeafletMapView
        markers={mapView.markers}
        center={mapView.center}
        bounds={mapView.bounds}
        defaultZoom={mapView.defaultZoom}
        focusedZoom={mapView.focusedZoom}
        selectedMarkerId={mapView.selectedMarkerId}
        onSelectMarker={mapView.selectMarker} />
    </div>
  );
}

Google Maps page

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import {
  DocyrusGoogleMapView,
  useDocyrusMapView
} from '@docyrus/ui/library/hooks/use-docyrus-map-view';

export function WarehouseMapPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const mapView = useDocyrusMapView({
    client,
    appSlug: 'base',
    dataSourceSlug: 'warehouse',
    locationFieldSlug: 'location',
    titleFieldSlug: 'name',
    descriptionFieldSlugs: ['city', 'status'],
    googleMapsApiKey: import.meta.env.VITE_GOOGLE_MAPS_API_KEY
  });

  return (
    <DocyrusGoogleMapView
      apiKey={mapView.googleMapsApiKey}
      markers={mapView.markers}
      center={mapView.center}
      bounds={mapView.bounds}
      selectedMarkerId={mapView.selectedMarkerId}
      onSelectMarker={mapView.selectMarker} />
  );
}

How the query is built

Internally the hook reuses the saved-view state from useDocyrusDataGrid, then creates its own items query with a stronger columns list.

That means a user can save a view that hides map_location, but the hook will still request:

• id
• the location field
• the resolved title field
• any popup/description fields you configured

So markers keep rendering correctly while the rest of the data-view behavior still follows the active Docyrus view.

Field resolution

Location field

Resolution order:

1. locationFieldSlug
2. first field with type === 'field-locationSelect'

Title field

Resolution order:

1. titleFieldSlug
2. first matching slug from: name, title, label, subject, display_name, displayName, commercial_title, short_name
3. first text-like field that is not the location field

Description fields

Resolution order:

1. descriptionFieldSlugs
2. first matching slugs from: description, details, address, city, district, country, state, province, status, type

Marker visual (image + icon)

Each marker can render as either a circular avatar (from an image field) or a Docyrus icon, with a configurable priority.

Image field (markerImageFieldSlug):

• Reads field-image / field-file payloads (array of { signed_url, url, src })
• Renders as a 36×36 circular avatar with a white ring

Icon field (markerIconFieldSlug):

• Reads a Docyrus icon identifier string such as "huge building-06" or "fal star"
• Auto-detected from field-icon type or the icon slug when omitted
• Renders the same SVG asset used by DocyrusIcon inside a 32×32 white badge

Priority (markerPriority):

• 'image' (default): image when present → icon when present → default MapPin
• 'icon': icon when present → default MapPin (image is ignored)

Icon color (markerIconColorFieldSlug + markerIconColor):

• Per-record color via the field, with a static fallback through markerIconColor
• Accepts hex, rgb(), CSS variables, or Tailwind tokens like "emerald-500" (resolved via resolveColorHex)
• Leaflet recolors the icon itself via CSS mask-image
• Google Maps renders the icon URL natively and does not support recoloring; the color value is ignored on that provider

The hook exposes the resolved values on each marker as marker.imageUrl, marker.iconUrl, and marker.iconColor. Custom renderMarkerIcon / getMarkerIcon callbacks should return null (Leaflet) or fall through (Google) when either is set to let the built-in renderer take over.

Viewport filter

When enableViewportFilter is true, markers / mappedItems are narrowed to records whose position falls inside the active map bounds. allMarkers keeps the unfiltered set.

Two modes:

• auto (default) — every pan/zoom updates the filter. Side lists and counts feel "live".
• manual — the filter only applies when searchThisArea() is called. isViewportStale becomes true when the user moves the map without confirming, perfect for an Airbnb-style button.

// Manual mode "Search this area" button
{mapView.isViewportStale && (
  <Button onClick={mapView.searchThisArea}>Search this area</Button>
)}

Wire the map → hook connection by passing mapView.setViewportBounds to the onViewportChange prop of DocyrusLeafletMapView / DocyrusGoogleMapView.

API Reference

useDocyrusMapView(options)

The hook accepts all useDocyrusDataGrid options except enableItemsQuery, showSelectColumn, and enableRowMarkers, plus the options below.

Return value

DocyrusLeafletMapView

Renders the hook's marker model on top of the Docyrus UI Leaflet map.

DocyrusGoogleMapView

Renders the same marker model on Google Maps.

Type Exports