Smart OSM Map #

A production-ready Flutter package for OpenStreetMap integration. It provides clustered markers, image support, user location display, and nearby filtering with animated radius effects.

Built on top of flutter_map, this package offers a "plug-and-play" experience with strong UX defaults, privacy-safe location handling, and a clean API.

Showcase #

Map UI with teardrop clusters

Map UI with user location

Map UI with image markers

Features #

• Clustered Markers: Automatically clusters markers to reduce clutter and improve performance. Can be disabled if needed.
• Custom Cluster Styling: Provide your own clusterBuilder to customize how clustered markers look.
• Image Markers: Supports both network images and local asset images for markers.
• User Location: Optional support to show the user's current location with safe permission handling.
• Nearby Filtering: Filter markers within a configurable radius from the user, complete with an animated ripple effect.
• Map Controls: Flexible control over initialCenter, initialZoom, minZoom, maxZoom, and onMapReady callbacks.
• No API Keys: Uses OpenStreetMap tiles, requiring no API keys for standard usage.

Installation #

Add smart_osm_map to your pubspec.yaml:

dependencies:
  smart_osm_map: ^1.0.0

Usage #

1. Define Your Data Model #

First, define the data you want to display on the map. This can be any Dart class.

class Place {
  final String name;
  final double lat;
  final double lng;
  final String image; // Asset path or network URL

  const Place({
    required this.name,
    required this.lat,
    required this.lng,
    required this.image,
  });
}

2. Basic Implementation #

Use the .simple constructor to map your data list to the map.

import 'package:smart_osm_map/smart_osm_map.dart';

class MyMapScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Your list of places
    final List<Place> places = [ /* ... */ ];

    return Scaffold(
      body: SmartOsmMap.simple(
        items: places,
        // Extract location data
        latitude: (place) => place.lat,
        longitude: (place) => place.lng,
        // Extract marker image (optional)
        markerImage: (place) => place.image, 
        // Handle taps
        onTap: (place) {
          print('Tapped on ${place.name}');
        },
      ),
    );
  }
}

3. Advanced Features & Customization #

The following example demonstrates how to enable user location, toggle "Nearby" filtering, and customize the map style within a StatefulWidget.

class SmartMapPlayground extends StatefulWidget {
  @override
  State<SmartMapPlayground> createState() => _SmartMapPlaygroundState();
}

class _SmartMapPlaygroundState extends State<SmartMapPlayground> {
  bool showUserLocation = false;
  bool enableNearby = false;

  @override
  Widget build(BuildContext context) {
    return SmartOsmMap.simple(
      items: places,
      latitude: (p) => p.lat,
      longitude: (p) => p.lng,
      markerImage: (p) => p.image,

      // --- Feature 1: User Location ---
      // Toggle this boolean to show/hide the user's location.
      // The package handles permission requests automatically.
      showUserLocation: showUserLocation,

      // --- Feature 2: Nearby Filtering ---
      // When enabled, only shows items within `nearbyRadiusKm` of the user.
      enableNearby: enableNearby,
      nearbyRadiusKm: 10, 

      // --- Feature 3: Styling ---
      markerSize: 64,
      markerBorderColor: Colors.deepPurple,
      clusterColor: Colors.black87,
      radiusColor: Colors.deepPurple.withOpacity(0.3),
      
      // --- Feature 4: Interaction ---
      onTap: (place) {
        // Handle marker tap (e.g., show a modal or navigate)
        showModalBottomSheet(
          context: context, 
          builder: (_) => Text(place.name),
        );
      },
      
      // --- Feature 5: Permission Handling ---
      // Optional callbacks to handle permission states in your UI
      onLocationPermissionDenied: () {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('Location permission is required.')),
        );
      },
    );
  }
}

Common Use Cases #

🏬 Store & ATM Locator #

Perfect for displaying branches or ATMs with custom branding. Use the nearbyRadiusKm to show only the closest locations to the user.

🏡 Real Estate Lists #

Show properties on a map with high-quality images. Use clustering to keep the view clean in high-density areas like city centers.

🍱 Food Delivery & Services #

Display partner restaurants or service providers. Use onTap to show detailed menus or service info in a bottom sheet.

Configuration #

OS Permissions #

This package uses geolocator to handle location. You must configure your app for location access.

Android #

Add the following to your <project>/android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS #

Add the following to your <project>/ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location when open to show nearby places.</string>

Privacy & Safety #

• No Tracking: smart_osm_map does not track user location in the background.
• No Data Collection: Location data is processed locally on the device to render the user layer and calculate distances. It is never sent to any external server by this package.
• Store Friendly: Designed to comply with Apple App Store and Google Play Store privacy guidelines regarding location usage.

Performance & Large Datasets #

While smart_osm_map is optimized for high performance, following these tips will ensure a smooth 60 FPS experience:

• Enable Clustering: For datasets over 100 items, always keep useClustering: true. This significantly reduces the number of widgets rendered on screen.
• Lightweight Models: Pass only the necessary data to the items list. If your items have large nested objects, consider mapping them to a lighter "MapItem" model.
• Image Optimization: Avoid using high-resolution 4K images for markers. Use thumbnails (e.g., 200x200px) to reduce memory overhead.
• Coordinate Precision: Coordinates are processed locally. For thousands of points, ensure your data source provides clean double values.

Troubleshooting #

OS Permissions #